summaryrefslogtreecommitdiff
path: root/src/lib/ecore_ipc/Ecore_Ipc.h
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.h
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.h261
1 files changed, 256 insertions, 5 deletions
diff --git a/src/lib/ecore_ipc/Ecore_Ipc.h b/src/lib/ecore_ipc/Ecore_Ipc.h
index 301ea24c43..928ade94c7 100644
--- a/src/lib/ecore_ipc/Ecore_Ipc.h
+++ b/src/lib/ecore_ipc/Ecore_Ipc.h
@@ -33,6 +33,7 @@
33 * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions. 33 * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions.
34 * @ingroup Ecore 34 * @ingroup Ecore
35 * 35 *
36 * Functions that set up and shut down the Ecore IPC Library.
36 * 37 *
37 * @{ 38 * @{
38 */ 39 */
@@ -325,37 +326,287 @@ EAPI extern int ECORE_IPC_EVENT_SERVER_DEL;
325EAPI extern int ECORE_IPC_EVENT_CLIENT_DATA; 326EAPI extern int ECORE_IPC_EVENT_CLIENT_DATA;
326EAPI extern int ECORE_IPC_EVENT_SERVER_DATA; 327EAPI extern int ECORE_IPC_EVENT_SERVER_DATA;
327 328
329/**
330 * @brief Initialises the Ecore IPC library.
331 * @return Number of times the library has been initialised without
332 * being shut down.
333 * @ingroup Ecore_IPC_Group
334 */
328EAPI int ecore_ipc_init(void); 335EAPI int ecore_ipc_init(void);
336
337/**
338 * @brief Shuts down the Ecore IPC library.
339 * @return Number of times the library has been initialised without being
340 * shut down.
341 * @ingroup Ecore_IPC_Group
342 */
329EAPI int ecore_ipc_shutdown(void); 343EAPI int ecore_ipc_shutdown(void);
330 344
331/* FIXME: need to add protocol type parameter */ 345/**
346 * @defgroup Ecore_IPC_Server_Group IPC Server Functions
347 * @ingroup Ecore_IPC_Group
348 *
349 * Functions the deal with IPC server objects.
350 */
351
352/**
353 * @brief Creates an IPC server that listens for connections.
354 *
355 * For more details about the @p compl_type, @p name and @p port
356 * parameters, see the @ref ecore_con_server_add documentation.
357 *
358 * @param compl_type The connection type.
359 * @param name Name to associate with the socket used for connection.
360 * @param port Number to identify with socket used for connection.
361 * @param data Data to associate with the IPC server.
362 * @return New IPC server. If there is an error, @c NULL is returned.
363 * @ingroup Ecore_IPC_Server_Group
364 * @todo Need to add protocol type parameter to this function.
365 */
332EAPI Ecore_Ipc_Server *ecore_ipc_server_add(Ecore_Ipc_Type type, const char *name, int port, const void *data); 366EAPI Ecore_Ipc_Server *ecore_ipc_server_add(Ecore_Ipc_Type type, const char *name, int port, const void *data);
333 367
334/* FIXME: need to add protocol type parameter */ 368/**
369 * @brief Creates an IPC server object to represent the IPC server listening
370 * on the given port.
371 *
372 * For more details about the @p compl_type, @p name and @p port
373 * parameters, see the @ref ecore_con_server_connect documentation.
374 *
375 * @param compl_type The IPC connection type.
376 * @param name Name used to determine which socket to use for the
377 * IPC connection.
378 * @param port Number used to identify the socket to use for the
379 * IPC connection.
380 * @param data Data to associate with the server.
381 * @return A new IPC server. @c NULL is returned on error.
382 * @ingroup Ecore_IPC_Server_Group
383 * @todo Need to add protocol type parameter.
384 */
335EAPI Ecore_Ipc_Server *ecore_ipc_server_connect(Ecore_Ipc_Type type, char *name, int port, const void *data); 385EAPI Ecore_Ipc_Server *ecore_ipc_server_connect(Ecore_Ipc_Type type, char *name, int port, const void *data);
386
387/**
388 * @brief Closes the connection and frees the given IPC server.
389 * @param svr The given IPC server.
390 * @return The data associated with the server when it was created.
391 * @ingroup Ecore_IPC_Server_Group
392 */
336EAPI void *ecore_ipc_server_del(Ecore_Ipc_Server *svr); 393EAPI void *ecore_ipc_server_del(Ecore_Ipc_Server *svr);
394
395/**
396 * @brief Retrieves the data associated with the given IPC server.
397 * @param svr The given IPC server.
398 * @return The associated data.
399 * @ingroup Ecore_IPC_Server_Group
400 */
337EAPI void *ecore_ipc_server_data_get(Ecore_Ipc_Server *svr); 401EAPI void *ecore_ipc_server_data_get(Ecore_Ipc_Server *svr);
402
403/**
404 * @brief Retrieves whether the given IPC server is currently connected.
405 * @param svr The given IPC server.
406 * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise.
407 * @ingroup Ecore_IPC_Server_Group
408 */
338EAPI Eina_Bool ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr); 409EAPI Eina_Bool ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr);
410
411/**
412 * @brief Retrieves the list of clients for this server.
413 * @param svr The given IPC server.
414 * @return An Eina_List with the clients.
415 * @ingroup Ecore_IPC_Server_Group
416 */
339EAPI Eina_List *ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr); 417EAPI Eina_List *ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr);
340/* FIXME: this needs to become an ipc message */ 418
419/**
420 * @brief Sends a message to the given IPC server.
421 *
422 * The content of the parameters, excluding the @p svr parameter, is up to
423 * the client.
424 *
425 * @param svr The given IPC server.
426 * @param major Major opcode of the message.
427 * @param minor Minor opcode of the message.
428 * @param ref Message reference number.
429 * @param ref_to Reference number of the message this message refers to.
430 * @param response Requires response.
431 * @param data The data to send as part of the message.
432 * @param size Length of the data, in bytes, to send.
433 * @return Number of bytes sent. @c 0 is returned if there is an error.
434 * @ingroup Ecore_IPC_Server_Group
435 * @todo This function needs to become an IPC message.
436 * @todo Fix up the documentation: Make sure what ref_to and response are.
437 */
341EAPI int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size); 438EAPI int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size);
439
440/**
441 * @brief Sets a limit on the number of clients that can be handled concurrently
442 * by the given server, and a policy on what to do if excess clients try to
443 * connect.
444 * Beware that if you set this once ecore is already running, you may
445 * already have pending CLIENT_ADD events in your event queue. Those
446 * clients have already connected and will not be affected by this call.
447 * Only clients subsequently trying to connect will be affected.
448 * @param svr The given server.
449 * @param client_limit The maximum number of clients to handle
450 * concurrently. -1 means unlimited (default). 0
451 * effectively disables the server.
452 * @param reject_excess_clients Set to 1 to automatically disconnect
453 * excess clients as soon as they connect if you are
454 * already handling client_limit clients. Set to 0
455 * (default) to just hold off on the "accept()"
456 * system call until the number of active clients
457 * drops. This causes the kernel to queue up to 4096
458 * connections (or your kernel's limit, whichever is
459 * lower).
460 * @ingroup Ecore_Ipc_Server_Group
461 */
342EAPI void ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients); 462EAPI void ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients);
463
464/**
465 * @brief Sets the max data payload size for an Ipc message in bytes
466 *
467 * @param svr The given server.
468 * @param size The maximum data payload size in bytes.
469 * @ingroup Ecore_Ipc_Server_Group
470 */
343EAPI void ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *srv, int size); 471EAPI void ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *srv, int size);
472
473/**
474 * @brief Gets the max data payload size for an Ipc message in bytes
475 *
476 * @param svr The given server.
477 * @return The maximum data payload in bytes.
478 * @ingroup Ecore_Ipc_Server_Group
479 */
344EAPI int ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *srv); 480EAPI int ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *srv);
481
482/**
483 * @brief Gets the IP address of a server that has been connected to.
484 *
485 * @param svr The given server.
486 * @return A pointer to an internal string that contains the IP address of
487 * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
488 * This string should not be modified or trusted to stay valid after
489 * deletion for the @p svr object. If no IP is known NULL is returned.
490 * @ingroup Ecore_Ipc_Server_Group
491 */
345EAPI const char *ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr); 492EAPI const char *ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr);
493
494/**
495 * @brief Flushes all pending data to the given server. Will return when done.
496 *
497 * @param svr The given server.
498 * @ingroup Ecore_Ipc_Server_Group
499 */
346EAPI void ecore_ipc_server_flush(Ecore_Ipc_Server *svr); 500EAPI void ecore_ipc_server_flush(Ecore_Ipc_Server *svr);
347 501
348/* FIXME: this needs to become an ipc message */ 502/**
503 * @defgroup Ecore_IPC_Client_Group IPC Client Functions
504 * @ingroup Ecore_IPC_Group
505 *
506 * Functions that deal with IPC client objects.
507 */
508
509/**
510 * @brief Sends a message to the given IPC client.
511 *
512 * @param cl The given IPC client.
513 * @param major Major opcode of the message.
514 * @param minor Minor opcode of the message.
515 * @param ref Reference number of the message.
516 * @param ref_to Reference number of the message this message refers to.
517 * @param response Requires response.
518 * @param data The data to send as part of the message.
519 * @param size Length of the data, in bytes, to send.
520 * @return The number of bytes sent. @c 0 will be returned if there is
521 * an error.
522 * @ingroup Ecore_IPC_Client_Group
523 * @todo This function needs to become an IPC message.
524 * @todo Make sure ref_to and response parameters are described correctly.
525 */
349EAPI int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size); 526EAPI int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size);
527
528/**
529 * @brief Retrieves the IPC server that the given IPC client is connected to.
530 *
531 * @param cl The given IPC client.
532 * @return The IPC server the IPC client is connected to.
533 * @ingroup Ecore_IPC_Client_Group
534 */
350EAPI Ecore_Ipc_Server *ecore_ipc_client_server_get(Ecore_Ipc_Client *cl); 535EAPI Ecore_Ipc_Server *ecore_ipc_client_server_get(Ecore_Ipc_Client *cl);
536
537/**
538 * @brief Closes the connection and frees memory allocated to the given IPC
539 * client.
540 *
541 * @param cl The given client.
542 * @return Data associated with the client.
543 * @ingroup Ecore_IPC_Client_Group
544 */
351EAPI void *ecore_ipc_client_del(Ecore_Ipc_Client *cl); 545EAPI void *ecore_ipc_client_del(Ecore_Ipc_Client *cl);
546
547/**
548 * @brief Sets the IPC data associated with the given IPC client to @p data.
549 *
550 * @param cl The given IPC client.
551 * @param data The data to associate with the IPC client.
552 * @ingroup Ecore_IPC_Client_Group
553 */
352EAPI void ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data); 554EAPI void ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data);
555
556/**
557 * @brief Retrieves the data that has been associated with the given IPC client.
558 *
559 * @param cl The given client.
560 * @return The data associated with the IPC client.
561 * @ingroup Ecore_IPC_Client_Group
562 */
353EAPI void *ecore_ipc_client_data_get(Ecore_Ipc_Client *cl); 563EAPI void *ecore_ipc_client_data_get(Ecore_Ipc_Client *cl);
564
565/**
566 * @brief Sets the max data payload size for an Ipc message in bytes
567 *
568 * @param cl The given client.
569 * @param size The maximum data payload size in bytes.
570 * @ingroup Ecore_Ipc_Client_Group
571 */
354EAPI void ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size); 572EAPI void ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size);
573
574/**
575 * @brief Gets the max data payload size for an Ipc message in bytes
576 *
577 * @param cl The given client.
578 * @return The maximum data payload size in bytes on success, @c -1 on failure.
579 * @ingroup Ecore_Ipc_Client_Group
580 */
355EAPI int ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl); 581EAPI int ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl);
582
583/**
584 * @brief Gets the IP address of a client that has been connected to.
585 *
586 * @param cl The given client.
587 * @return A pointer to an internal string that contains the IP address of
588 * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation.
589 * This string should not be modified or trusted to stay valid after
590 * deletion for the @p cl object. If no IP is known @c NULL is
591 * returned.
592 * @ingroup Ecore_Ipc_Client_Group
593 */
356EAPI const char *ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl); 594EAPI const char *ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl);
595
596/**
597 * @brief Flushes all pending data to the given client. Will return when done.
598 *
599 * @param cl The given client.
600 * @ingroup Ecore_Ipc_Client_Group
601 */
357EAPI void ecore_ipc_client_flush(Ecore_Ipc_Client *cl); 602EAPI void ecore_ipc_client_flush(Ecore_Ipc_Client *cl);
358 603
604/**
605 * @brief Returns if SSL support is available
606 *
607 * @return 1 if SSL is available, 0 if it is not.
608 * @ingroup Ecore_Con_Client_Group
609 */
359EAPI int ecore_ipc_ssl_available_get(void); 610EAPI int ecore_ipc_ssl_available_get(void);
360/* FIXME: need to add a callback to "ok" large ipc messages greater than */ 611/* FIXME: need to add a callback to "ok" large ipc messages greater than */
361/* a certain size (security/DOS attack safety) */ 612/* a certain size (security/DOS attack safety) */