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 may call udscs_destroy_connection, in which case
  43  * *connp must be made NULL (which udscs_destroy_connection takes care of).
  44  */
  45 typedef void (*udscs_read_callback)(struct udscs_connection **connp,
  46     struct udscs_message_header *header, uint8_t *data);
  47
  48 /* Callbacks with this type will be called when the connection is disconnected.
  49  * Note:
  50  * 1) udscs will destroy the connection in question itself after
  51  *    this callback has completed!
  52  * 2) This callback is always called, even if the disconnect is initiated
  53  *    by the udscs user through returning -1 from a read callback, or
  54  *    by explictly calling udscs_destroy_connection.
  55  */
  56 typedef void (*udscs_disconnect_callback)(struct udscs_connection *conn);
  57
  58 /* Connect to a unix domain socket named name. */
  59 struct udscs_connection *udscs_connect(const char *socketname,
  60     udscs_read_callback read_callback,
  61     udscs_disconnect_callback disconnect_callback,
  62     const char * const type_to_string[], int no_types, int debug);
  63
  64 /* The contents of connp will be made NULL. */
  65 void udscs_destroy_connection(struct udscs_connection **connp);
  66
  67 int udscs_client_fill_fds(struct udscs_connection *conn, fd_set *readfds,
  68     fd_set *writefds);
  69
  70 /* Note the connection may be destroyed (when disconnected) by this call
  71  * in this case the disconnect calllback will get called before the
  72  * destruction and the contents of connp will be made NULL.
  73  */
  74 void udscs_client_handle_fds(struct udscs_connection **connp, fd_set *readfds,
  75     fd_set *writefds);
  76
  77 /* Queue a message for delivery to the client connected through conn.
  78  * Returns 0 on success -1 on error (only happens when malloc fails).
  79  */
  80 int udscs_write(struct udscs_connection *conn, uint32_t type, uint32_t arg1,
  81         uint32_t arg2, const uint8_t *data, uint32_t size);
  82
  83 /* To associate per connection data with a connection. */
  84 void udscs_set_user_data(struct udscs_connection *conn, void *data);
  85 void *udscs_get_user_data(struct udscs_connection *conn);
  86
  87
  88 #ifndef UDSCS_NO_SERVER
  89
  90 /* ---------- Server-side API ---------- */
  91
  92 struct udscs_server;
  93
  94 /* Callbacks with this type will be called when a new connection to a
  95  * server is accepted.
  96  */
  97 typedef void (*udscs_connect_callback)(struct udscs_connection *conn);
  98
  99 /* Create a unix domain socket named name and start listening on it. */
 100 struct udscs_server *udscs_create_server(const char *socketname,
 101     udscs_connect_callback connect_callback,
 102     udscs_read_callback read_callback,
 103     udscs_disconnect_callback disconnect_callback,
 104     const char * const type_to_string[], int no_types, int debug);
 105
 106 void udscs_destroy_server(struct udscs_server *server);
 107
 108 /* Like udscs_write, but then send the message to all clients connected to
 109  * the server.
 110  */
 111 int udscs_server_write_all(struct udscs_server *server,
 112     uint32_t type, uint32_t arg1, uint32_t arg2,
 113     const uint8_t *data, uint32_t size);
 114
 115 /* Callback type for udscs_server_for_all_clients. Clients can be disconnected
 116  * from this callback just like with a read callback.
 117  */
 118 typedef int (*udscs_for_all_clients_callback)(struct udscs_connection **connp,
 119     void *priv);
 120
 121 /* Call func for all clients connected to the server, passing through
 122  * priv to all func calls. Returns the total of the return values from all
 123  * calls to func.
 124  */
 125 int udscs_server_for_all_clients(struct udscs_server *server,
 126     udscs_for_all_clients_callback func, void *priv);
 127
 128 /* Given an udscs server or client fill the fd_sets pointed to by readfds and
 129  * writefds for select() usage.
 130  * Return value: value of the highest fd + 1
 131  */
 132 int udscs_server_fill_fds(struct udscs_server *server, fd_set *readfds,
 133     fd_set *writefds);
 134
 135 /* Handle any events flagged by select for the given udscs server or client. */
 136 void udscs_server_handle_fds(struct udscs_server *server, fd_set *readfds,
 137     fd_set *writefds);
 138
 139 /* Returns the peer's user credentials. */
 140 struct ucred udscs_get_peer_cred(struct udscs_connection *conn);
 141
 142 #endif
 143
 144 #endif