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                  SilcNotifyPayload notify_payload);
  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                         SilcCommandStatus status, SilcCommand command, ...);
  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 } SilcClientOperations;
  61
  62 /*
  63    Descriptions of above operation functions:
  64
  65    void (*say)(SilcClient client, SilcClientConnection conn, char *msg, ...);
  66
  67    Message sent to the application by library. `conn' associates the
  68    message to a specific connection.  `conn', however, may be NULL.
  69
  70
  71    void (*channel_message)(client, SilcClientConnection conn,
  72                            char *sender, char *channel_name, char *msg);
  73
  74    Message for a channel. The `sender' is the nickname of the sender
  75    received in the packet. The `channel_name' is the name of the channel.
  76
  77
  78    void (*private_message)(client, SilcClientConnection conn,
  79                            char *sender, char *msg);
  80
  81    Private message to the client. The `sender' is the nickname of the
  82    sender received in the packet.
  83
  84
  85    void (*notify)(SilcClient client, SilcClientConnection conn,
  86                   SilcNotifyPayload notify_payload);
  87
  88    Notify message to the client.  The `notify_payload' is the Notify
  89    Payload received from server.  Client library may parse it to cache
  90    some data received from the payload but it is the application's
  91    responsiblity to retrieve the message and arguments from the payload.
  92    The message in the payload sent by server is implementation specific
  93    thus it is recommended that application will generate its own message.
  94
  95
  96    void (*command)(SilcClient client, SilcClientConnection conn,
  97                    SilcClientCommandContext cmd_context, int success,
  98                    SilcCommand command);
  99
 100    Command handler. This function is called always in the command function.
 101    If error occurs it will be called as well. `conn' is the associated
 102    client connection. `cmd_context' is the command context that was
 103    originally sent to the command. `success' is FALSE if error occured
 104    during command. `command' is the command being processed. It must be
 105    noted that this is not reply from server. This is merely called just
 106    after application has called the command. Just to tell application
 107    that the command really was processed.
 108
 109
 110    void (*command_reply)(SilcClient client, SilcClientConnection conn,
 111                          SilcCommandPayload cmd_payload, int success,
 112                          SilcCommandStatus status, SilcCommand command, ...);
 113
 114    Command reply handler. This function is called always in the command reply
 115    function. If error occurs it will be called as well. Normal scenario
 116    is that it will be called after the received command data has been parsed
 117    and processed. The function is used to pass the received command data to
 118    the application.
 119
 120    `conn' is the associated client connection. `cmd_payload' is the command
 121    payload data received from server and it can be ignored. It is provided
 122    if the application would like to re-parse the received command data,
 123    however, it must be noted that the data is parsed already by the library
 124    thus the payload can be ignored. `success' is FALSE if error occured.
 125    In this case arguments are not sent to the application. The `status' is
 126    the command reply status server returned. The `command' is the command
 127    reply being processed. The function has variable argument list and each
 128    command defines the number and type of arguments it passes to the
 129    application (on error they are not sent).
 130
 131
 132    void (*connect)(SilcClient client, SilcClientConnection conn, int success);
 133
 134    Called to indicate that connection was either successfully established
 135    or connecting failed.  This is also the first time application receives
 136    the SilcClientConnection objecet which it should save somewhere.
 137
 138
 139    void (*disconnect)(SilcClient client, SilcClientConnection conn);
 140
 141    Called to indicate that connection was disconnected to the server.
 142
 143
 144    int (*get_auth_method)(SilcClient client, SilcClientConnection conn,
 145                           char *hostname, unsigned short port,
 146                           SilcProtocolAuthMeth *auth_meth,
 147                           unsigned char **auth_data,
 148                           unsigned int *auth_data_len);
 149
 150    Find authentication method and authentication data by hostname and
 151    port. The hostname may be IP address as well. The found authentication
 152    method and authentication data is returned to `auth_meth', `auth_data'
 153    and `auth_data_len'. The function returns TRUE if authentication method
 154    is found and FALSE if not. `conn' may be NULL.
 155
 156
 157    int (*verify_server_key)(SilcClient client, SilcClientConnection conn,
 158                             unsigned char *pk, unsigned int pk_len,
 159                             SilcSKEPKType pk_type);
 160
 161    Verifies received public key. The public key has been received from
 162    a server. If user decides to trust the key may be saved as trusted
 163    server key for later use. If user does not trust the key this returns
 164    FALSE. If everything is Ok this returns TRUE.
 165
 166
 167    unsigned char *(*ask_passphrase)(SilcClient client,
 168                                     SilcClientConnection conn);
 169
 170    Ask (interact, that is) a passphrase from user. Returns the passphrase
 171    or NULL on error.
 172
 173 */
 174
 175 #endif