lib/silcclient/ops.h

   1 /*
   2
   3   ops.h
   4
   5   Author: Pekka Riikonen <priikone@poseidon.pspt.fi>
   6
   7   Copyright (C) 2000 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; either version 2 of the License, or
  12   (at your option) any later version.
  13
  14   This program is distributed in the hope that it will be useful,
  15   but WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17   GNU General Public License for more details.
  18
  19 */
  20
  21 #ifndef OPS_H
  22 #define OPS_H
  23
  24 /*
  25  * SILC Client Operations
  26  *
  27  * These functions must be implemented by the application calling the
  28  * SILC client library. The client library can call these functions at
  29  * any time.
  30  *
  31  * To use this structure: define a static SilcClientOperations variable,
  32  * fill it and pass its pointer to silc_client_alloc function.
  33  */
  34 typedef struct {
  35   void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...);
  36   void (*channel_message)(SilcClient client, SilcClientConnection conn,
  37                           SilcClientEntry sender, SilcChannelEntry channel,
  38                           char *msg);
  39   void (*private_message)(SilcClient client, SilcClientConnection conn,
  40                           SilcClientEntry sender, char *msg);
  41   void (*notify)(SilcClient client, SilcClientConnection conn,
  42                  SilcNotifyType type, ...);
  43   void (*command)(SilcClient client, SilcClientConnection conn,
  44                   SilcClientCommandContext cmd_context, int success,
  45                   SilcCommand command);
  46   void (*command_reply)(SilcClient client, SilcClientConnection conn,
  47                         SilcCommandPayload cmd_payload, int success,
  48                         SilcCommand command, SilcCommandStatus status, ...);
  49   void (*connect)(SilcClient client, SilcClientConnection conn, int success);
  50   void (*disconnect)(SilcClient client, SilcClientConnection conn);
  51   int (*get_auth_method)(SilcClient client, SilcClientConnection conn,
  52                          char *hostname, unsigned short port,
  53                          SilcProtocolAuthMeth *auth_meth,
  54                          unsigned char **auth_data,
  55                          unsigned int *auth_data_len);
  56   int (*verify_server_key)(SilcClient client, SilcClientConnection conn,
  57                            unsigned char *pk, unsigned int pk_len,
  58                            SilcSKEPKType pk_type);
  59   unsigned char *(*ask_passphrase)(SilcClient client,
  60                                    SilcClientConnection conn);
  61   void (*failure)(SilcClient client, SilcClientConnection conn,
  62                   SilcProtocol protocol, void *failure);
  63 } SilcClientOperations;
  64
  65 /*
  66    Descriptions of above operation functions:
  67
  68    void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...);
  69
  70    Message sent to the application by library. `conn' associates the
  71    message to a specific connection.  `conn', however, may be NULL.
  72
  73
  74    void (*channel_message)(SilcClient client, SilcClientConnection conn,
  75                            SilcClientEntry client, SilcChannelEntry channel,
  76                            char *msg);
  77
  78    Message for a channel. The `sender' is the sender of the message
  79    The `channel' is the channel.
  80
  81
  82    void (*private_message)(SilcClient client, SilcClientConnection conn,
  83                            char *sender, char *msg);
  84
  85    Private message to the client. The `sender' is the sender of the
  86    message.
  87
  88
  89    void (*notify)(SilcClient client, SilcClientConnection conn, ...);
  90
  91    Notify message to the client. The notify arguments are sent in the
  92    same order as servers sends them. The arguments are same as received
  93    from the server except for ID's.  If ID is received application receives
  94    the corresponding entry to the ID. For example, if Client ID is received
  95    application receives SilcClientEntry.  Also, if the notify type is
  96    for channel the channel entry is sent to application (even if server
  97    does not send it because client library gets the channel entry from
  98    the Channel ID in the packet's header).
  99
 100
 101    void (*command)(SilcClient client, SilcClientConnection conn,
 102                    SilcClientCommandContext cmd_context, int success,
 103                    SilcCommand command);
 104
 105    Command handler. This function is called always in the command function.
 106    If error occurs it will be called as well. `conn' is the associated
 107    client connection. `cmd_context' is the command context that was
 108    originally sent to the command. `success' is FALSE if error occured
 109    during command. `command' is the command being processed. It must be
 110    noted that this is not reply from server. This is merely called just
 111    after application has called the command. Just to tell application
 112    that the command really was processed.
 113
 114
 115    void (*command_reply)(SilcClient client, SilcClientConnection conn,
 116                          SilcCommandPayload cmd_payload, int success,
 117                          SilcCommandStatus status, SilcCommand command, ...);
 118
 119    Command reply handler. This function is called always in the command reply
 120    function. If error occurs it will be called as well. Normal scenario
 121    is that it will be called after the received command data has been parsed
 122    and processed. The function is used to pass the received command data to
 123    the application.
 124
 125    `conn' is the associated client connection. `cmd_payload' is the command
 126    payload data received from server and it can be ignored. It is provided
 127    if the application would like to re-parse the received command data,
 128    however, it must be noted that the data is parsed already by the library
 129    thus the payload can be ignored. `success' is FALSE if error occured.
 130    In this case arguments are not sent to the application. The `status' is
 131    the command reply status server returned. The `command' is the command
 132    reply being processed. The function has variable argument list and each
 133    command defines the number and type of arguments it passes to the
 134    application (on error they are not sent).
 135
 136
 137    void (*connect)(SilcClient client, SilcClientConnection conn, int success);
 138
 139    Called to indicate that connection was either successfully established
 140    or connecting failed.  This is also the first time application receives
 141    the SilcClientConnection objecet which it should save somewhere.
 142
 143
 144    void (*disconnect)(SilcClient client, SilcClientConnection conn);
 145
 146    Called to indicate that connection was disconnected to the server.
 147
 148
 149    int (*get_auth_method)(SilcClient client, SilcClientConnection conn,
 150                           char *hostname, unsigned short port,
 151                           SilcProtocolAuthMeth *auth_meth,
 152                           unsigned char **auth_data,
 153                           unsigned int *auth_data_len);
 154
 155    Find authentication method and authentication data by hostname and
 156    port. The hostname may be IP address as well. The found authentication
 157    method and authentication data is returned to `auth_meth', `auth_data'
 158    and `auth_data_len'. The function returns TRUE if authentication method
 159    is found and FALSE if not. `conn' may be NULL.
 160
 161
 162    int (*verify_server_key)(SilcClient client, SilcClientConnection conn,
 163                             unsigned char *pk, unsigned int pk_len,
 164                             SilcSKEPKType pk_type);
 165
 166    Verifies received public key. The public key has been received from
 167    a server. If user decides to trust the key may be saved as trusted
 168    server key for later use. If user does not trust the key this returns
 169    FALSE. If everything is Ok this returns TRUE.
 170
 171
 172    unsigned char *(*ask_passphrase)(SilcClient client,
 173                                     SilcClientConnection conn);
 174
 175    Ask (interact, that is) a passphrase from user. Returns the passphrase
 176    or NULL on error.
 177
 178
 179    void (*failure)(SilcClient client, SilcClientConnection conn,
 180                    SilcProtocol protocol, void *failure);
 181
 182    Notifies application that failure packet was received.  This is called
 183    if there is some protocol active in the client.  The `protocol' is the
 184    protocol context.  The `failure' is opaque pointer to the failure
 185    indication.  Note, that the `failure' is protocol dependant and application
 186    must explicitly cast it to correct type.  Usually `failure' is 32 bit
 187    failure type (see protocol specs for all protocol failure types).
 188
 189 */
 190
 191 #endif