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