summaryrefslogtreecommitdiff
path: root/src/lib/ecore_ipc/ecore_ipc.c
diff options
context:
space:
mode:
authorJee-Yong Um <conr2d@gmail.com>2016-10-04 21:08:17 +0900
committerHermet Park <hermet@hermet.pe.kr>2016-10-04 21:08:17 +0900
commit3b4293ffa334303ccd2de0422d56a21873afcba0 (patch)
tree51ac1118cb56068bc74f2985120dcee688543ba9 /src/lib/ecore_ipc/ecore_ipc.c
parent72125bd8c3e5e3d2d28d847c1a0ab4e02e3dccc8 (diff)
ecore_file/ipc: clean up documentation
Summary: move comment from c source to header and adjust ingroup relationship Reviewers: cedric, jpeg, Hermet Reviewed By: Hermet Differential Revision: https://phab.enlightenment.org/D4328
Diffstat (limited to '')
-rw-r--r--src/lib/ecore_ipc/ecore_ipc.c240
1 files changed, 4 insertions, 236 deletions
diff --git a/src/lib/ecore_ipc/ecore_ipc.c b/src/lib/ecore_ipc/ecore_ipc.c
index 219c9503b6..0e6c2865d0 100644
--- a/src/lib/ecore_ipc/ecore_ipc.c
+++ b/src/lib/ecore_ipc/ecore_ipc.c
@@ -231,19 +231,6 @@ static int _ecore_ipc_init_count = 0;
231static Eina_List *servers = NULL; 231static Eina_List *servers = NULL;
232static Ecore_Event_Handler *handler[6]; 232static Ecore_Event_Handler *handler[6];
233 233
234/**
235 * @defgroup Ecore_IPC_Library_Group Ecore_IPC - Inter Process Communication Library Functions
236 * @ingroup Ecore
237 *
238 * Functions that set up and shut down the Ecore IPC Library.
239 */
240
241/**
242 * Initialises the Ecore IPC library.
243 * @return Number of times the library has been initialised without
244 * being shut down.
245 * @ingroup Ecore_IPC_Library_Group
246 */
247EAPI int 234EAPI int
248ecore_ipc_init(void) 235ecore_ipc_init(void)
249{ 236{
@@ -283,12 +270,6 @@ ecore_ipc_init(void)
283 return _ecore_ipc_init_count; 270 return _ecore_ipc_init_count;
284} 271}
285 272
286/**
287 * Shuts down the Ecore IPC library.
288 * @return Number of times the library has been initialised without being
289 * shut down.
290 * @ingroup Ecore_IPC_Library_Group
291 */
292EAPI int 273EAPI int
293ecore_ipc_shutdown(void) 274ecore_ipc_shutdown(void)
294{ 275{
@@ -311,27 +292,7 @@ ecore_ipc_shutdown(void)
311 return _ecore_ipc_init_count; 292 return _ecore_ipc_init_count;
312} 293}
313 294
314/** 295/* FIXME: need to add protocol type parameter */
315 * @defgroup Ecore_IPC_Server_Group IPC Server Functions
316 * @ingroup Ecore_IPC_Library_Group
317 *
318 * Functions the deal with IPC server objects.
319 */
320
321/**
322 * Creates an IPC server that listens for connections.
323 *
324 * For more details about the @p compl_type, @p name and @p port
325 * parameters, see the @ref ecore_con_server_add documentation.
326 *
327 * @param compl_type The connection type.
328 * @param name Name to associate with the socket used for connection.
329 * @param port Number to identify with socket used for connection.
330 * @param data Data to associate with the IPC server.
331 * @return New IPC server. If there is an error, @c NULL is returned.
332 * @ingroup Ecore_IPC_Server_Group
333 * @todo Need to add protocol type parameter to this function.
334 */
335EAPI Ecore_Ipc_Server * 296EAPI Ecore_Ipc_Server *
336ecore_ipc_server_add(Ecore_Ipc_Type compl_type, const char *name, int port, const void *data) 297ecore_ipc_server_add(Ecore_Ipc_Type compl_type, const char *name, int port, const void *data)
337{ 298{
@@ -373,23 +334,7 @@ ecore_ipc_server_add(Ecore_Ipc_Type compl_type, const char *name, int port, cons
373 return svr; 334 return svr;
374} 335}
375 336
376/** 337/* FIXME: need to add protocol type parameter */
377 * Creates an IPC server object to represent the IPC server listening
378 * on the given port.
379 *
380 * For more details about the @p compl_type, @p name and @p port
381 * parameters, see the @ref ecore_con_server_connect documentation.
382 *
383 * @param compl_type The IPC connection type.
384 * @param name Name used to determine which socket to use for the
385 * IPC connection.
386 * @param port Number used to identify the socket to use for the
387 * IPC connection.
388 * @param data Data to associate with the server.
389 * @return A new IPC server. @c NULL is returned on error.
390 * @ingroup Ecore_IPC_Server_Group
391 * @todo Need to add protocol type parameter.
392 */
393EAPI Ecore_Ipc_Server * 338EAPI Ecore_Ipc_Server *
394ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const void *data) 339ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const void *data)
395{ 340{
@@ -433,12 +378,6 @@ ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const
433 return svr; 378 return svr;
434} 379}
435 380
436/**
437 * Closes the connection and frees the given IPC server.
438 * @param svr The given IPC server.
439 * @return The data associated with the server when it was created.
440 * @ingroup Ecore_IPC_Server_Group
441 */
442EAPI void * 381EAPI void *
443ecore_ipc_server_del(Ecore_Ipc_Server *svr) 382ecore_ipc_server_del(Ecore_Ipc_Server *svr)
444{ 383{
@@ -475,12 +414,6 @@ ecore_ipc_server_del(Ecore_Ipc_Server *svr)
475 return data; 414 return data;
476} 415}
477 416
478/**
479 * Retrieves the data associated with the given IPC server.
480 * @param svr The given IPC server.
481 * @return The associated data.
482 * @ingroup Ecore_IPC_Server_Group
483 */
484EAPI void * 417EAPI void *
485ecore_ipc_server_data_get(Ecore_Ipc_Server *svr) 418ecore_ipc_server_data_get(Ecore_Ipc_Server *svr)
486{ 419{
@@ -493,12 +426,6 @@ ecore_ipc_server_data_get(Ecore_Ipc_Server *svr)
493 return svr->data; 426 return svr->data;
494} 427}
495 428
496/**
497 * Retrieves whether the given IPC server is currently connected.
498 * @param svr The given IPC server.
499 * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise.
500 * @ingroup Ecore_IPC_Server_Group
501 */
502EAPI Eina_Bool 429EAPI Eina_Bool
503ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr) 430ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr)
504{ 431{
@@ -511,12 +438,6 @@ ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr)
511 return ecore_con_server_connected_get(svr->server); 438 return ecore_con_server_connected_get(svr->server);
512} 439}
513 440
514/**
515 * Retrieves the list of clients for this server.
516 * @param svr The given IPC server.
517 * @return An Eina_List with the clients.
518 * @ingroup Ecore_IPC_Server_Group
519 */
520EAPI Eina_List * 441EAPI Eina_List *
521ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr) 442ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr)
522{ 443{
@@ -561,25 +482,7 @@ ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr)
561 s += 1; \ 482 s += 1; \
562 } 483 }
563 484
564/** 485/* FIXME: this needs to become an ipc message */
565 * Sends a message to the given IPC server.
566 *
567 * The content of the parameters, excluding the @p svr parameter, is up to
568 * the client.
569 *
570 * @param svr The given IPC server.
571 * @param major Major opcode of the message.
572 * @param minor Minor opcode of the message.
573 * @param ref Message reference number.
574 * @param ref_to Reference number of the message this message refers to.
575 * @param response Requires response.
576 * @param data The data to send as part of the message.
577 * @param size Length of the data, in bytes, to send.
578 * @return Number of bytes sent. @c 0 is returned if there is an error.
579 * @ingroup Ecore_IPC_Server_Group
580 * @todo This function needs to become an IPC message.
581 * @todo Fix up the documentation: Make sure what ref_to and response are.
582 */
583EAPI int 486EAPI int
584ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size) 487ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size)
585{ 488{
@@ -622,28 +525,6 @@ ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int
622 return ret; 525 return ret;
623} 526}
624 527
625/**
626 * Sets a limit on the number of clients that can be handled concurrently
627 * by the given server, and a policy on what to do if excess clients try to
628 * connect.
629 * Beware that if you set this once ecore is already running, you may
630 * already have pending CLIENT_ADD events in your event queue. Those
631 * clients have already connected and will not be affected by this call.
632 * Only clients subsequently trying to connect will be affected.
633 * @param svr The given server.
634 * @param client_limit The maximum number of clients to handle
635 * concurrently. -1 means unlimited (default). 0
636 * effectively disables the server.
637 * @param reject_excess_clients Set to 1 to automatically disconnect
638 * excess clients as soon as they connect if you are
639 * already handling client_limit clients. Set to 0
640 * (default) to just hold off on the "accept()"
641 * system call until the number of active clients
642 * drops. This causes the kernel to queue up to 4096
643 * connections (or your kernel's limit, whichever is
644 * lower).
645 * @ingroup Ecore_Ipc_Server_Group
646 */
647EAPI void 528EAPI void
648ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients) 529ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients)
649{ 530{
@@ -656,13 +537,6 @@ ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char
656 ecore_con_server_client_limit_set(svr->server, client_limit, reject_excess_clients); 537 ecore_con_server_client_limit_set(svr->server, client_limit, reject_excess_clients);
657} 538}
658 539
659/**
660 * Sets the max data payload size for an Ipc message in bytes
661 *
662 * @param svr The given server.
663 * @param size The maximum data payload size in bytes.
664 * @ingroup Ecore_Ipc_Server_Group
665 */
666EAPI void 540EAPI void
667ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *svr, int size) 541ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *svr, int size)
668{ 542{
@@ -675,13 +549,6 @@ ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *svr, int size)
675 svr->max_buf_size = size; 549 svr->max_buf_size = size;
676} 550}
677 551
678/**
679 * Gets the max data payload size for an Ipc message in bytes
680 *
681 * @param svr The given server.
682 * @return The maximum data payload in bytes.
683 * @ingroup Ecore_Ipc_Server_Group
684 */
685EAPI int 552EAPI int
686ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *svr) 553ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *svr)
687{ 554{
@@ -694,16 +561,6 @@ ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *svr)
694 return svr->max_buf_size; 561 return svr->max_buf_size;
695} 562}
696 563
697/**
698 * Gets the IP address of a server that has been connected to.
699 *
700 * @param svr The given server.
701 * @return A pointer to an internal string that contains the IP address of
702 * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
703 * This string should not be modified or trusted to stay valid after
704 * deletion for the @p svr object. If no IP is known NULL is returned.
705 * @ingroup Ecore_Ipc_Server_Group
706 */
707EAPI const char * 564EAPI const char *
708ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr) 565ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr)
709{ 566{
@@ -716,12 +573,6 @@ ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr)
716 return ecore_con_server_ip_get(svr->server); 573 return ecore_con_server_ip_get(svr->server);
717} 574}
718 575
719/**
720 * Flushes all pending data to the given server. Will return when done.
721 *
722 * @param svr The given server.
723 * @ingroup Ecore_Ipc_Server_Group
724 */
725EAPI void 576EAPI void
726ecore_ipc_server_flush(Ecore_Ipc_Server *svr) 577ecore_ipc_server_flush(Ecore_Ipc_Server *svr)
727{ 578{
@@ -766,29 +617,7 @@ ecore_ipc_server_flush(Ecore_Ipc_Server *svr)
766 s += 1; \ 617 s += 1; \
767 } 618 }
768 619
769/** 620/* FIXME: this needs to become an ipc message */
770 * @defgroup Ecore_IPC_Client_Group IPC Client Functions
771 * @ingroup Ecore_IPC_Library_Group
772 *
773 * Functions that deal with IPC client objects.
774 */
775
776/**
777 * Sends a message to the given IPC client.
778 * @param cl The given IPC client.
779 * @param major Major opcode of the message.
780 * @param minor Minor opcode of the message.
781 * @param ref Reference number of the message.
782 * @param ref_to Reference number of the message this message refers to.
783 * @param response Requires response.
784 * @param data The data to send as part of the message.
785 * @param size Length of the data, in bytes, to send.
786 * @return The number of bytes sent. @c 0 will be returned if there is
787 * an error.
788 * @ingroup Ecore_IPC_Client_Group
789 * @todo This function needs to become an IPC message.
790 * @todo Make sure ref_to and response parameters are described correctly.
791 */
792EAPI int 621EAPI int
793ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size) 622ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size)
794{ 623{
@@ -833,12 +662,6 @@ ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int r
833 return ret; 662 return ret;
834} 663}
835 664
836/**
837 * Retrieves the IPC server that the given IPC client is connected to.
838 * @param cl The given IPC client.
839 * @return The IPC server the IPC client is connected to.
840 * @ingroup Ecore_IPC_Client_Group
841 */
842EAPI Ecore_Ipc_Server * 665EAPI Ecore_Ipc_Server *
843ecore_ipc_client_server_get(Ecore_Ipc_Client *cl) 666ecore_ipc_client_server_get(Ecore_Ipc_Client *cl)
844{ 667{
@@ -851,13 +674,6 @@ ecore_ipc_client_server_get(Ecore_Ipc_Client *cl)
851 return cl->svr; 674 return cl->svr;
852} 675}
853 676
854/**
855 * Closes the connection and frees memory allocated to the given IPC
856 * client.
857 * @param cl The given client.
858 * @return Data associated with the client.
859 * @ingroup Ecore_IPC_Client_Group
860 */
861EAPI void * 677EAPI void *
862ecore_ipc_client_del(Ecore_Ipc_Client *cl) 678ecore_ipc_client_del(Ecore_Ipc_Client *cl)
863{ 679{
@@ -887,12 +703,6 @@ ecore_ipc_client_del(Ecore_Ipc_Client *cl)
887 return data; 703 return data;
888} 704}
889 705
890/**
891 * Sets the IPC data associated with the given IPC client to @p data.
892 * @param cl The given IPC client.
893 * @param data The data to associate with the IPC client.
894 * @ingroup Ecore_IPC_Client_Group
895 */
896EAPI void 706EAPI void
897ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data) 707ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data)
898{ 708{
@@ -905,12 +715,6 @@ ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data)
905 cl->data = (void *)data; 715 cl->data = (void *)data;
906} 716}
907 717
908/**
909 * Retrieves the data that has been associated with the given IPC client.
910 * @param cl The given client.
911 * @return The data associated with the IPC client.
912 * @ingroup Ecore_IPC_Client_Group
913 */
914EAPI void * 718EAPI void *
915ecore_ipc_client_data_get(Ecore_Ipc_Client *cl) 719ecore_ipc_client_data_get(Ecore_Ipc_Client *cl)
916{ 720{
@@ -923,13 +727,6 @@ ecore_ipc_client_data_get(Ecore_Ipc_Client *cl)
923 return cl->data; 727 return cl->data;
924} 728}
925 729
926/**
927 * Sets the max data payload size for an Ipc message in bytes
928 *
929 * @param cl The given client.
930 * @param size The maximum data payload size in bytes.
931 * @ingroup Ecore_Ipc_Client_Group
932 */
933EAPI void 730EAPI void
934ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size) 731ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size)
935{ 732{
@@ -942,13 +739,6 @@ ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size)
942 cl->max_buf_size = size; 739 cl->max_buf_size = size;
943} 740}
944 741
945/**
946 * Gets the max data payload size for an Ipc message in bytes
947 *
948 * @param cl The given client.
949 * @return The maximum data payload size in bytes on success, @c -1 on failure.
950 * @ingroup Ecore_Ipc_Client_Group
951 */
952EAPI int 742EAPI int
953ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl) 743ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl)
954{ 744{
@@ -961,17 +751,6 @@ ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl)
961 return cl->max_buf_size; 751 return cl->max_buf_size;
962} 752}
963 753
964/**
965 * Gets the IP address of a client that has been connected to.
966 *
967 * @param cl The given client.
968 * @return A pointer to an internal string that contains the IP address of
969 * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
970 * This string should not be modified or trusted to stay valid after
971 * deletion for the @p cl object. If no IP is known @c NULL is
972 * returned.
973 * @ingroup Ecore_Ipc_Client_Group
974 */
975EAPI const char * 754EAPI const char *
976ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl) 755ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl)
977{ 756{
@@ -984,12 +763,6 @@ ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl)
984 return ecore_con_client_ip_get(cl->client); 763 return ecore_con_client_ip_get(cl->client);
985} 764}
986 765
987/**
988 * Flushes all pending data to the given client. Will return when done.
989 *
990 * @param cl The given client.
991 * @ingroup Ecore_Ipc_Client_Group
992 */
993EAPI void 766EAPI void
994ecore_ipc_client_flush(Ecore_Ipc_Client *cl) 767ecore_ipc_client_flush(Ecore_Ipc_Client *cl)
995{ 768{
@@ -1002,11 +775,6 @@ ecore_ipc_client_flush(Ecore_Ipc_Client *cl)
1002 ecore_con_client_flush(cl->client); 775 ecore_con_client_flush(cl->client);
1003} 776}
1004 777
1005/**
1006 * Returns if SSL support is available
1007 * @return 1 if SSL is available, 0 if it is not.
1008 * @ingroup Ecore_Con_Client_Group
1009 */
1010EAPI int 778EAPI int
1011ecore_ipc_ssl_available_get(void) 779ecore_ipc_ssl_available_get(void)
1012{ 780{