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 <stdio.h>
  26 #include <stdint.h>
  27 #include <sys/select.h>
  28 #include <sys/socket.h>
  29
  30
  31 /* ---------- Generic bits and client-side API ---------- */
  32
  33 struct udscs_connection;
  34 struct udscs_message_header {
  35     uint32_t type;
  36     uint32_t arg1;
  37     uint32_t arg2;
  38     uint32_t size;
  39 };
  40
  41 /* Callbacks with this type will be called when a complete message has been
  42  * received. The callback does not own the data buffer and should not free it.
  43  * The data buffer will be freed shortly after the read callback returns.
  44  * The callback may call udscs_destroy_connection, in which case *connp must be
  45  * made NULL (which udscs_destroy_connection takes care of).
  46  */
  47 typedef void (*udscs_read_callback)(struct udscs_connection **connp,
  48     struct udscs_message_header *header, uint8_t *data);
  49
  50 /* Callbacks with this type will be called when the connection is disconnected.
  51  * Note:
  52  * 1) udscs will destroy the connection in question itself after
  53  *    this callback has completed!
  54  * 2) This callback is always called, even if the disconnect is initiated
  55  *    by the udscs user through returning -1 from a read callback, or
  56  *    by explictly calling udscs_destroy_connection.
  57  */
  58 typedef void (*udscs_disconnect_callback)(struct udscs_connection *conn);
  59
  60 /* Connect to the unix domain socket specified by socketname.
  61  * Only sockets bound to a pathname are supported.
  62  *
  63  * If debug is true then the events on this connection will be traced.
  64  * This includes the incoming and outgoing message names. So when debug is true
  65  * no_types must be set to the value of the highest valid message id + 1,
  66  * and type_to_string must point to a string array of size no_types for
  67  * converting the message ids to their names.
  68  */
  69 struct udscs_connection *udscs_connect(const char *socketname,
  70     udscs_read_callback read_callback,
  71     udscs_disconnect_callback disconnect_callback,
  72     const char * const type_to_string[], int no_types, int debug);
  73
  74 /* Close the connection, releases the corresponding resources and
  75  * sets *connp to NULL.
  76  *
  77  * Does nothing if *connp is NULL.
  78  */
  79 void udscs_destroy_connection(struct udscs_connection **connp);
  80
  81 /* Given a udscs client, fill the fd_sets pointed to by readfds and
  82  * writefds for select() usage.
  83  * Return value: value of the highest fd + 1 or -1 if conn is NULL
  84  */
  85 int udscs_client_fill_fds(struct udscs_connection *conn, fd_set *readfds,
  86     fd_set *writefds);
  87
  88 /* Handle any events flagged by select for the given udscs client.
  89  * Note that upon disconnection this will call the disconnect callback
  90  * and then destroy the connection which will set *connp to NULL.
  91  *
  92  * Does nothing if *connp is NULL.
  93  */
  94 void udscs_client_handle_fds(struct udscs_connection **connp, fd_set *readfds,
  95     fd_set *writefds);
  96
  97 /* Queue a message for delivery to the client connected through conn.
  98  * Return value: 0 on success -1 on error (only happens when malloc fails).
  99  */
 100 int udscs_write(struct udscs_connection *conn, uint32_t type, uint32_t arg1,
 101         uint32_t arg2, const uint8_t *data, uint32_t size);
 102
 103 /* Associates the specified user data with the connection. */
 104 void udscs_set_user_data(struct udscs_connection *conn, void *data);
 105
 106 /* Return value: the connection's associated user data,
 107  * NULL if conn is NULL.
 108  */
 109 void *udscs_get_user_data(struct udscs_connection *conn);
 110
 111
 112 #ifndef UDSCS_NO_SERVER
 113
 114 /* ---------- Server-side API ---------- */
 115
 116 struct udscs_server;
 117
 118 /* Callbacks with this type will be called when a new connection to a
 119  * server is accepted.
 120  */
 121 typedef void (*udscs_connect_callback)(struct udscs_connection *conn);
 122
 123 /* Create the unix domain socket specified by socketname and
 124  * start listening on it.
 125  * Only sockets bound to a pathname are supported.
 126  *
 127  * If debug is true then the events on this socket and related individual
 128  * connections will be traced.
 129  * This includes the incoming and outgoing message names. So when debug is true
 130  * no_types must be set to the value of the highest valid message id + 1,
 131  * and type_to_string must point to a string array of size no_types for
 132  * converting the message ids to their names.
 133  */
 134 struct udscs_server *udscs_create_server(const char *socketname,
 135     udscs_connect_callback connect_callback,
 136     udscs_read_callback read_callback,
 137     udscs_disconnect_callback disconnect_callback,
 138     const char * const type_to_string[], int no_types, int debug);
 139
 140 /* Close all the server's connections and releases the corresponding
 141  * resources.
 142  * Does nothing if server is NULL.
 143  */
 144 void udscs_destroy_server(struct udscs_server *server);
 145
 146 /* Like udscs_write, but then send the message to all clients connected to
 147  * the server.
 148  */
 149 int udscs_server_write_all(struct udscs_server *server,
 150     uint32_t type, uint32_t arg1, uint32_t arg2,
 151     const uint8_t *data, uint32_t size);
 152
 153 /* Callback type for udscs_server_for_all_clients. Clients can be disconnected
 154  * from this callback just like with a read callback.
 155  */
 156 typedef int (*udscs_for_all_clients_callback)(struct udscs_connection **connp,
 157     void *priv);
 158
 159 /* Call func for all clients connected to the server, passing through
 160  * priv to all func calls. Returns the total of the return values from all
 161  * calls to func or 0 if server is NULL.
 162  */
 163 int udscs_server_for_all_clients(struct udscs_server *server,
 164     udscs_for_all_clients_callback func, void *priv);
 165
 166 /* Given a udscs server, fill the fd_sets pointed to by readfds and
 167  * writefds for select() usage.
 168  * Return value: value of the highest fd + 1 or -1 if server is NULL
 169  */
 170 int udscs_server_fill_fds(struct udscs_server *server, fd_set *readfds,
 171     fd_set *writefds);
 172
 173 /* Handle any events flagged by select for the given udscs server.
 174  * Does nothing if server is NULL.
 175  */
 176 void udscs_server_handle_fds(struct udscs_server *server, fd_set *readfds,
 177     fd_set *writefds);
 178
 179 /* Returns the peer's user credentials. */
 180 struct ucred udscs_get_peer_cred(struct udscs_connection *conn);
 181
 182 #endif
 183
 184 #endif