lib/silcserver/silcserver.h

   1 /*
   2
   3   silcserver.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 1997 - 2005 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* silcserver/Server Library Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  *
  25  ***/
  26
  27 #ifndef SILCSERVER_H
  28 #define SILCSERVER_H
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 #include "silcserver_params.h"
  35
  36 /****s* silcserver/SilcServerAPI/SilcServer
  37  *
  38  * NAME
  39  *
  40  *    typedef struct SilcServerStruct *SilcServer;
  41  *
  42  * DESCRIPTION
  43  *
  44  *    This context is the actual SILC Server context and is allocated
  45  *    by silc_server_alloc and given as argument to all silc_server_*
  46  *    functions.  It is freed by the silc_server_free function.
  47  *
  48  ***/
  49 typedef struct SilcServerStruct *SilcServer;
  50
  51 /****f* silcserver/SilcServerAPI/SilcServerRunning
  52  *
  53  * SYNOPSIS
  54  *
  55  *    typedef void (*SilcServerRunning)(SilcServer server, SilcBool running,
  56  *                                      void *context);
  57  *
  58  * DESCRIPTION
  59  *
  60  *    Called to indicate that the server is up and running and ready to
  61  *    accept new connection and create connections to remote router, if
  62  *    any has been configured.
  63  *
  64  ***/
  65 typedef void (*SilcServerRunning)(SilcServer server, void *context);
  66
  67 /****f* silcserver/SilcServerAPI/SilcServerStop
  68  *
  69  * SYNOPSIS
  70  *
  71  *    typedef void (*SilcServerStop)(SilcServer server, void *context);
  72  *
  73  * DESCRIPTION
  74  *
  75  *    Called to indicate that the server has stopped and can be freed now.
  76  *
  77  ***/
  78 typedef void (*SilcServerStop)(SilcServer server, void *context);
  79
  80 /****f* silcserver/SilcServerAPI/silc_server_alloc
  81  *
  82  * SYNOPSIS
  83  *
  84  *    SilcServer silc_server_alloc(void *app_context, SilcServerParams params,
  85  *                                 SilcSchedule schedule);
  86  *
  87  * DESCRIPTION
  88  *
  89  *    Allocates SILC server context and returns it.  Returns NULL if case
  90  *    of error.  The `app_context' is application specific context and
  91  *    can be retrieved from the server by using silc_server_get_context
  92  *    function.  The `params' context contains the SILC server parameters
  93  *    that application has gathered most likely from a configuration file
  94  *    or similar source.  The `params' and everything inside are allocated
  95  *    by the caller, but the server library will own it and free it.  It
  96  *    may also modify its content.
  97  *
  98  ***/
  99 SilcServer silc_server_alloc(void *app_context, SilcServerParams params,
 100                              SilcSchedule schedule);
 101
 102 /****f* silcserver/SilcServerAPI/silc_server_free
 103  *
 104  * SYNOPSIS
 105  *
 106  *    void silc_server_free(SilcServer server);
 107  *
 108  * DESCRIPTION
 109  *
 110  *    Free the server context and all allocated resources.
 111  *
 112  ***/
 113 void silc_server_free(SilcServer server);
 114
 115 /****f* silcserver/SilcServerAPI/silc_server_run
 116  *
 117  * SYNOPSIS
 118  *
 119  *    void silc_server_run(SilcServer server, SilcServerRunning running,
 120  *                         void *running_context);
 121  *
 122  * DESCRIPTION
 123  *
 124  *    Starts the SILC server.  This function returns immediately and the
 125  *    SilcSchedule must be run after this functions returns or it must be
 126  *    already running when this function is called.  The `running' callback
 127  *    will be called once the server is up and running.
 128  *
 129  ***/
 130 void silc_server_run(SilcServer server, SilcServerRunning running,
 131                      void *running_context);
 132
 133 /****f* silcserver/SilcServerAPI/silc_server_run
 134  *
 135  * SYNOPSIS
 136  *
 137  *    void silc_server_stop(SilcServer server, SilcServerStop stop_callback,
 138  *                          void *stop_context);
 139  *
 140  * DESCRIPTION
 141  *
 142  *    Stops the SILC server.  Stopping of the server is asynchronous and
 143  *    once it has stopped the `stopped' callback will be called with the
 144  *    `stop_context'.  Application should not exit without calling this
 145  *    function.
 146  *
 147  ***/
 148 void silc_server_stop(SilcServer server, SilcServerStop stopped,
 149                       void *stop_context);
 150
 151 #include "server_internal.h"
 152
 153 #ifdef __cplusplus
 154 }
 155 #endif
 156
 157 #endif /* SILCSERVER_H */