src/udscs.h

   1 /*  udscs.h Unix Domain Socket Client Server framework header file
   2
   3     Copyright 2010 Red Hat, Inc.
   4
   5     Red Hat Authors:
   6     Hans de Goede <hdegoede@redhat.com>
   7
   8     This program is free software: you can redistribute it and/or modify
   9     it under the terms of the GNU General Public License as published by
  10     the Free Software Foundation, either version 3 of the License, or
  11     (at your option) any later version.
  12
  13     This program is distributed in the hope that it will be useful,
  14     but WITHOUT ANY WARRANTY; without even the implied warranty of
  15     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16     GNU General Public License for more details.
  17
  18     You should have received a copy of the GNU General Public License
  19     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  20 */
  21
  22 #ifndef __UDSCS_H
  23 #define __UDSCS_H
  24
  25 #include <stdint.h>
  26 #include <sys/socket.h>
  27 #include <glib-object.h>
  28 #include "vdagent-connection.h"
  29
  30 G_BEGIN_DECLS
  31
  32 #define UDSCS_TYPE_CONNECTION udscs_connection_get_type()
  33 G_DECLARE_FINAL_TYPE(UdscsConnection, udscs_connection, UDSCS, CONNECTION, VDAgentConnection)
  34
  35 /* ---------- Generic bits and client-side API ---------- */
  36
  37 struct udscs_message_header {
  38     uint32_t type;
  39     uint32_t arg1;
  40     uint32_t arg2;
  41     uint32_t size;
  42 };
  43
  44 /* Callbacks with this type will be called when a complete message has been
  45  * received. The callback does not own the data buffer and should not free it.
  46  * The data buffer will be freed shortly after the read callback returns.
  47  */
  48 typedef void (*udscs_read_callback)(UdscsConnection *conn,
  49     struct udscs_message_header *header, uint8_t *data);
  50
  51 /* Connect to the unix domain socket specified by socketname.
  52  * Only sockets bound to a pathname are supported.
  53  *
  54  * If debug is true then the events on this connection will be traced.
  55  * This includes the incoming and outgoing message names.
  56  *
  57  * In case of failure, returns NULL and set @err with reason.
  58  */
  59 UdscsConnection *udscs_connect(const char *socketname,
  60     udscs_read_callback read_callback,
  61     VDAgentConnErrorCb error_cb,
  62     int debug,
  63     GError **err);
  64
  65 /* Queue a message for delivery to the client connected through conn.
  66  */
  67 void udscs_write(UdscsConnection *conn, uint32_t type, uint32_t arg1,
  68         uint32_t arg2, const uint8_t *data, uint32_t size);
  69
  70 #ifndef UDSCS_NO_SERVER
  71
  72 /* ---------- Server-side API ---------- */
  73
  74 struct udscs_server;
  75
  76 /* Callbacks with this type will be called when a new connection to a
  77  * server is accepted.
  78  */
  79 typedef void (*udscs_connect_callback)(UdscsConnection *conn);
  80
  81 /* Initialize a new udscs_server struct.
  82  *
  83  * If debug is true then the events on this socket and related individual
  84  * connections will be traced.
  85  * This includes the incoming and outgoing message names.
  86  */
  87 struct udscs_server *udscs_server_new(
  88     udscs_connect_callback connect_callback,
  89     udscs_read_callback read_callback,
  90     VDAgentConnErrorCb error_cb,
  91     int debug);
  92
  93 /* Start listening on a pre-configured socket specified by the given @fd.
  94  * This can be used with systemd socket activation, etc. */
  95 void udscs_server_listen_to_socket(struct udscs_server *server,
  96                                    gint                 fd,
  97                                    GError             **err);
  98
  99 /* Create a new socket, bind it to @address and start listening on it. */
 100 void udscs_server_listen_to_address(struct udscs_server *server,
 101                                     const gchar         *addr,
 102                                     GError             **err);
 103
 104 void udscs_server_start(struct udscs_server *server);
 105
 106 void udscs_server_destroy_connection(struct udscs_server *server,
 107                                      UdscsConnection     *conn);
 108
 109 /* Close all the server's connections and releases the corresponding
 110  * resources.
 111  * Does nothing if server is NULL.
 112  */
 113 void udscs_destroy_server(struct udscs_server *server);
 114
 115 /* Like udscs_write, but then send the message to all clients connected to
 116  * the server.
 117  */
 118 void udscs_server_write_all(struct udscs_server *server,
 119     uint32_t type, uint32_t arg1, uint32_t arg2,
 120     const uint8_t *data, uint32_t size);
 121
 122 /* Callback type for udscs_server_for_all_clients. Clients can be disconnected
 123  * from this callback just like with a read callback.
 124  */
 125 typedef int (*udscs_for_all_clients_callback)(UdscsConnection *conn,
 126     void *priv);
 127
 128 /* Call func for all clients connected to the server, passing through
 129  * priv to all func calls. Returns the total of the return values from all
 130  * calls to func or 0 if server is NULL.
 131  */
 132 int udscs_server_for_all_clients(struct udscs_server *server,
 133     udscs_for_all_clients_callback func, void *priv);
 134
 135 #endif
 136
 137 G_END_DECLS
 138
 139 #endif