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                         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                   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                          SilcCommandStatus status, 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. The `status' is
 122    the command reply status server returned. The `command' is the command
 123    reply being processed. The function has variable argument list and each
 124    command defines the number and type of arguments it passes to the
 125    application (on error they are not sent).
 126
 127
 128    void (*connect)(SilcClient client, SilcClientConnection conn, int success);
 129
 130    Called to indicate that connection was either successfully established
 131    or connecting failed.  This is also the first time application receives
 132    the SilcClientConnection objecet which it should save somewhere.
 133
 134
 135    void (*disconnect)(SilcClient client, SilcClientConnection conn);
 136
 137    Called to indicate that connection was disconnected to the server.
 138
 139
 140    int (*get_auth_method)(SilcClient client, SilcClientConnection conn,
 141                           char *hostname, unsigned short port,
 142                           SilcProtocolAuthMeth *auth_meth,
 143                           unsigned char **auth_data,
 144                           unsigned int *auth_data_len);
 145
 146    Find authentication method and authentication data by hostname and
 147    port. The hostname may be IP address as well. The found authentication
 148    method and authentication data is returned to `auth_meth', `auth_data'
 149    and `auth_data_len'. The function returns TRUE if authentication method
 150    is found and FALSE if not. `conn' may be NULL.
 151
 152
 153    int (*verify_server_key)(SilcClient client, SilcClientConnection conn,
 154                             unsigned char *pk, unsigned int pk_len,
 155                             SilcSKEPKType pk_type);
 156
 157    Verifies received public key. The public key has been received from
 158    a server. If user decides to trust the key may be saved as trusted
 159    server key for later use. If user does not trust the key this returns
 160    FALSE. If everything is Ok this returns TRUE.
 161
 162
 163    unsigned char *(*ask_passphrase)(SilcClient client,
 164                                     SilcClientConnection conn);
 165
 166    Ask (interact, that is) a passphrase from user. Returns the passphrase
 167    or NULL on error.
 168
 169 */
 170
 171 #endif