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, char *msg);
  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, ...);
  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                   SilcNotifyType type, char *msg);
  87
  88    Notify message to the client.  The `type' is the notify type received
  89    from server.  The `msg' is a human readable message sent by the server.
  90
  91
  92    void (*command)(SilcClient client, SilcClientConnection conn,
  93                    SilcClientCommandContext cmd_context, int success,
  94                    SilcCommand command);
  95
  96    Command handler. This function is called always in the command function.
  97    If error occurs it will be called as well. `conn' is the associated
  98    client connection. `cmd_context' is the command context that was
  99    originally sent to the command. `success' is FALSE if error occured
 100    during command. `command' is the command being processed. It must be
 101    noted that this is not reply from server. This is merely called just
 102    after application has called the command. Just to tell application
 103    that the command really was processed.
 104
 105
 106    void (*command_reply)(SilcClient client, SilcClientConnection conn,
 107                          SilcCommandPayload cmd_payload, int success,
 108                          SilcCommand command, ...);
 109
 110    Command reply handler. This function is called always in the command reply
 111    function. If error occurs it will be called as well. Normal scenario
 112    is that it will be called after the received command data has been parsed
 113    and processed. The function is used to pass the received command data to
 114    the application.
 115
 116    `conn' is the associated client connection. `cmd_payload' is the command
 117    payload data received from server and it can be ignored. It is provided
 118    if the application would like to re-parse the received command data,
 119    however, it must be noted that the data is parsed already by the library
 120    thus the payload can be ignored. `success' is FALSE if error occured.
 121    In this case arguments are not sent to the application. `command' is the
 122    command reply being processed. The function has variable argument list
 123    and each command defines the number and type of arguments it passes to the
 124    application (on error they are not sent).
 125
 126
 127    void (*connect)(SilcClient client, SilcClientConnection conn, int success);
 128
 129    Called to indicate that connection was either successfully established
 130    or connecting failed.  This is also the first time application receives
 131    the SilcClientConnection objecet which it should save somewhere.
 132
 133
 134    void (*disconnect)(SilcClient client, SilcClientConnection conn);
 135
 136    Called to indicate that connection was disconnected to the server.
 137
 138
 139    int (*get_auth_method)(SilcClient client, SilcClientConnection conn,
 140                           char *hostname, unsigned short port,
 141                           SilcProtocolAuthMeth *auth_meth,
 142                           unsigned char **auth_data,
 143                           unsigned int *auth_data_len);
 144
 145    Find authentication method and authentication data by hostname and
 146    port. The hostname may be IP address as well. The found authentication
 147    method and authentication data is returned to `auth_meth', `auth_data'
 148    and `auth_data_len'. The function returns TRUE if authentication method
 149    is found and FALSE if not. `conn' may be NULL.
 150
 151
 152    int (*verify_server_key)(SilcClient client, SilcClientConnection conn,
 153                             unsigned char *pk, unsigned int pk_len,
 154                             SilcSKEPKType pk_type);
 155
 156    Verifies received public key. The public key has been received from
 157    a server. If user decides to trust the key may be saved as trusted
 158    server key for later use. If user does not trust the key this returns
 159    FALSE. If everything is Ok this returns TRUE.
 160
 161
 162    unsigned char *(*ask_passphrase)(SilcClient client,
 163                                     SilcClientConnection conn);
 164
 165    Ask (interact, that is) a passphrase from user. Returns the passphrase
 166    or NULL on error.
 167
 168 */
 169
 170 #endif