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