lib/silcutil/silclocalnetstream.h

   1 /*
   2
   3   silclocalnetstream.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2008 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  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 */
  19
  20 /****h* silcutil/Local Network Stream Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Local network stream interface enables two or more processes to communicate
  25  * with each other in the local machine using the local network.  The
  26  * interface provides a form of interprocess communication (IPC) using network
  27  * sockets (TCP).
  28  *
  29  * Since the implementation uses real TCP network socket the listener can be
  30  * used for any TCP communication, however connections may be estalished only
  31  * from the local machine.  The connections use the loopback network.
  32  *
  33  * EXAMPLE
  34  *
  35  * // Create listener
  36  * listener = silc_local_net_create_listener("/tmp/conn1", 0, schedule,
  37  *                                           accept_callback, ctx);
  38  *
  39  * // Connect to the listener
  40  * silc_local_net_connect("/tmp/conn1", schedule, connected_callback, ctx);
  41  *
  42  * // Close listener
  43  * silc_local_net_close_listener(listener);
  44  *
  45  ***/
  46
  47 #ifndef SILCLOCALNETSTREAM_H
  48 #define SILCLOCALNETSTREAM_H
  49
  50 /****d* silcutil/SilcLocalNetSecurity
  51  *
  52  * NAME
  53  *
  54  *    typedef enum { ... } SilcLocalNetSecurity
  55  *
  56  * DESCRIPTION
  57  *
  58  *    The security flags for the local network listener.  They specify
  59  *    how the listener can be accessed.  The flags are a bitmasks and can
  60  *    be combined.  Note that, these flags apply only when this API is
  61  *    used.  Anyone in local machine is able to see the network listener
  62  *    port by checking all bound network listeners and thus are able to
  63  *    connect to it.
  64  *
  65  * SOURCE
  66  */
  67 typedef enum {
  68   SILC_LOCAL_NET_ALL    = 0x0000,     /* Anyone in local machine can connect */
  69   SILC_LOCAL_NET_USER   = 0x0001,     /* Same user can connect */
  70   SILC_LOCAL_NET_GROUP  = 0x0002,     /* Same group can connect */
  71 } SilcLocalNetSecurity;
  72 /***/
  73
  74 /****f* silcutil/silc_local_net_create_listener
  75  *
  76  * SYNOPSIS
  77  *
  78  *    SilcNetListener
  79  *    silc_local_net_create_listener(const char *filepath,
  80  *                                   SilcLocalNetSecurity security,
  81  *                                   SilcSchedule schedule,
  82  *                                   SilcNetCallback callback,
  83  *                                   void *context);
  84  *
  85  * DESCRIPTION
  86  *
  87  *    Creates a local network stream listener and returns a network server.
  88  *    The `filepath' is a local filepath that must be used by the clients to
  89  *    connect to the server.  The `security' specify the access method to
  90  *    the listener.  It can specify for example that only the user creating
  91  *    the listener is able to connect to it.
  92  *
  93  *    The `callback' will be called when a client connects to the listener
  94  *    with the `context'.  The returned stream to the `callback' is a
  95  *    socket stream (silcsocketstream.h).  The returned listener must be
  96  *    closed by calling silc_local_net_close_listener.
  97  *
  98  *    Clients can connect to the listener by calling the
  99  *    silc_local_net_connect.
 100  *
 101  *    Returns NULL on error and set silc_errno.  If `schedule' is NULL this
 102  *    will call silc_schedule_get_global to try to get global scheduler.
 103  *
 104  ***/
 105 SilcNetListener silc_local_net_create_listener(const char *filepath,
 106                                                SilcLocalNetSecurity security,
 107                                                SilcSchedule schedule,
 108                                                SilcNetCallback callback,
 109                                                void *context);
 110
 111 /****f* silcutil/silc_local_net_close_listener
 112  *
 113  * SYNOPSIS
 114  *
 115  *    void silc_local_net_close_listener(SilcNetListener local_listener);
 116  *
 117  * DESCRIPTION
 118  *
 119  *    Closes the local network stream listener.
 120  *
 121  ***/
 122 void silc_local_net_close_listener(SilcNetListener local_listener);
 123
 124 /****f* silcutil/silc_local_net_connect
 125  *
 126  * SYNOPSIS
 127  *
 128  *    SilcAsyncOperation silc_local_net_connect(const char *filepath,
 129  *                                              SilcSchedule schedule,
 130  *                                              SilcNetCallback callback,
 131  *                                              void *context);
 132  *
 133  * DESCRIPTION
 134  *
 135  *    Connects to the local network server at the provided `filepath'.  If
 136  *    the `filepath' does not exist or is not valid local network listener
 137  *    the connection will fail.
 138  *
 139  *    The `callback' with `context' will be called once the connection has
 140  *    been created.  The stream returned to `callback' is a socket stream
 141  *    (silcsocketstream.h).  SilcStream API can be used with the returned
 142  *    stream.  The stream must be destroyed by calling silc_stream_destroy.
 143  *
 144  *    If `schedule' is NULL this will call silc_schedule_get_global to try
 145  *    to get global scheduler.
 146  *
 147  ***/
 148 SilcAsyncOperation silc_local_net_connect(const char *filepath,
 149                                           SilcSchedule schedule,
 150                                           SilcNetCallback callback,
 151                                           void *context);
 152
 153 #endif /* SILCLOCALNETSTREAM_H */