lib/silcclient/silcclient_entry.h

   1 /*
   2
   3   silcclient_entry.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2006 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; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 #ifndef SILCCLIENT_ENTRY_H
  21 #define SILCCLIENT_ENTRY_H
  22
  23 #ifndef SILCCLIENT_H
  24 #error "Do not include this header directly, include silcclient.h instead"
  25 #endif
  26
  27 /****s* silcclient/SilcClientAPI/SilcClientEntry
  28  *
  29  * NAME
  30  *
  31  *    typedef struct SilcClientEntryStruct { ... } *SilcClientEntry;
  32  *
  33  * DESCRIPTION
  34  *
  35  *    This structure represents a client or a user in the SILC network.
  36  *    The local user has this structure also and it can be accessed from
  37  *    SilcClientConnection structure.  All other users in the SILC network
  38  *    that are accessed using the Client Library routines will have their
  39  *    own SilcClientEntry structure.  For example, when finding users by
  40  *    their nickname the Client Library returns this structure back to
  41  *    the application.  All strings in the structure are UTF-8 encoded.
  42  *
  43  *    Application may store its own pointer into the context pointer in
  44  *    this structure.
  45  *
  46  * NOTES
  47  *
  48  *    If application wants to store nickname or any of the other strings
  49  *    it should always duplicated them.
  50  *
  51  *    None of the string arrays are set if the first character is '\0'.
  52  *    All string arrays are always NULL terminated.
  53  *
  54  *    If application stores the SilcClientEntry it must always take
  55  *    a reference of it by calling silc_client_ref_client function.  The
  56  *    reference must be released after it is not needed anymore by calling
  57  *    silc_client_unref_client function.
  58  *
  59  * SOURCE
  60  */
  61 struct SilcClientEntryStruct {
  62   char nickname[128 + 1];            /* Nickname */
  63   char username[128 + 1];            /* Username */
  64   char hostname[256 + 1];            /* Hostname */
  65   char server  [256 + 1];            /* SILC server name */
  66   char *realname;                    /* Realname (userinfo) */
  67   char *nickname_normalized;         /* Normalized nickname */
  68
  69   SilcClientID id;                   /* The Client ID */
  70   SilcUInt32 mode;                   /* User mode in SILC, see SilcUserMode */
  71   SilcPublicKey public_key;          /* User's public key, may be NULL */
  72   SilcHashTable channels;            /* Channels client has joined */
  73   SilcDList attrs;                   /* Requested Attributes (maybe NULL) */
  74   unsigned char fingerprint[20];     /* SHA-1 fingerprint of the public key */
  75
  76   void *context;                     /* Application specific context */
  77   SilcClientEntryInternal internal;
  78 };
  79 /***/
  80
  81 /****s* silcclient/SilcClientAPI/SilcChannelEntry
  82  *
  83  * NAME
  84  *
  85  *    typedef struct SilcChannelEntryStruct { ... } *SilcChannelEntry;
  86  *
  87  * DESCRIPTION
  88  *
  89  *    This structure represents a channel in the SILC network.  All
  90  *    channels that the client are aware of or have joined in will be
  91  *    represented as SilcChannelEntry.  The structure includes information
  92  *    about the channel.  All strings in the structure are UTF-8 encoded.
  93  *
  94  * SOURCE
  95  */
  96 struct SilcChannelEntryStruct {
  97   /* General information */
  98   char *channel_name;                        /* Channel name */
  99   SilcChannelID *id;                         /* Channel ID */
 100   SilcUInt32 mode;                           /* Channel mode, ChannelModes. */
 101   char *topic;                               /* Current topic, may be NULL */
 102   SilcPublicKey founder_key;                 /* Founder key, may be NULL */
 103   SilcUInt32 user_limit;                     /* User limit on channel */
 104
 105   /* All clients that has joined this channel.  The key to the table is the
 106      SilcClientEntry and the context is SilcChannelUser context. */
 107   SilcHashTable user_list;
 108
 109   /* Channel keys */
 110   SilcCipher channel_key;                    /* The channel key */
 111   unsigned char *key;                        /* Raw key data */
 112   SilcUInt32 key_len;                        /* Raw key data length */
 113   unsigned char iv[SILC_CIPHER_MAX_IV_SIZE]; /* Current IV */
 114   SilcHmac hmac;                             /* Current HMAC */
 115
 116   /* Channel private keys */
 117   SilcDList private_keys;                    /* List of private keys or NULL */
 118   SilcChannelPrivateKey curr_key;            /* Current private key */
 119
 120   /* SilcChannelEntry status information */
 121   SilcDList old_channel_keys;
 122   SilcDList old_hmacs;
 123   SilcUInt16 resolve_cmd_ident;              /* Command identifier when
 124                                                 resolving this entry */
 125
 126   /* Application specific data.  Application may set here whatever it wants. */
 127   void *context;
 128 };
 129 /***/
 130
 131 /****s* silcclient/SilcClientAPI/SilcServerEntry
 132  *
 133  * NAME
 134  *
 135  *    typedef struct SilcServerEntryStruct { ... } *SilcServerEntry
 136  *
 137  * DESCRIPTION
 138  *
 139  *    This structure represents a server in the SILC network.  All servers
 140  *    that the client is aware of and have for example resolved with
 141  *    SILC_COMMAND_INFO command have their on SilcServerEntry structure.
 142  *    All strings in the structure are UTF-8 encoded.
 143  *
 144  * SOURCE
 145  */
 146 struct SilcServerEntryStruct {
 147   /* General information */
 148   char *server_name;                         /* Server name */
 149   char *server_info;                         /* Server info */
 150   SilcServerID *server_id;                   /* Server ID */
 151   SilcUInt16 resolve_cmd_ident;              /* Command identifier when
 152                                                 resolving this entry */
 153
 154   /* Application specific data.  Application may set here whatever it wants. */
 155   void *context;
 156 };
 157 /***/
 158
 159 /* SilcClientEntry routines */
 160
 161 /****f* silcclient/SilcClientAPI/SilcGetClientCallback
 162  *
 163  * SYNOPSIS
 164  *
 165  *    typedef void (*SilcGetClientCallback)(SilcClient client,
 166  *                                          SilcClientConnection conn,
 167  *                                          SilcStatus status,
 168  *                                          SilcDList clients,
 169  *                                          void *context);
 170  *
 171  * DESCRIPTION
 172  *
 173  *    Callback function given to various client search functions.  The
 174  *    found entries are allocated into the `clients' list.  The list must
 175  *    not be freed by the receiver, the library will free it later.  If the
 176  *    `clients' is NULL, no such clients exist in the SILC Network, and
 177  *    the `status' will include the error.
 178  *
 179  * NOTES
 180  *
 181  *    If the application stores any of the SilcClientEntry pointers from
 182  *    the `clients' list it must reference it with silc_client_ref_client
 183  *    function.
 184  *
 185  *    Application must not free the returned `clients' list.
 186  *
 187  ***/
 188 typedef void (*SilcGetClientCallback)(SilcClient client,
 189                                       SilcClientConnection conn,
 190                                       SilcStatus status,
 191                                       SilcDList clients,
 192                                       void *context);
 193
 194 /****f* silcclient/SilcClientAPI/silc_client_ref_client
 195  *
 196  * SYNOPSIS
 197  *
 198  *    void silc_client_ref_client(SilcClient client,
 199  *                                SilcClientConnection conn,
 200  *                                SilcClientEntry client_entry);
 201  *
 202  * DESCRIPTION
 203  *
 204  *    Takes a reference of the client entry indicated by `client_entry'
 205  *    The reference must be released by calling silc_client_unref_client
 206  *    after it is not needed anymore.
 207  *
 208  ***/
 209 void silc_client_ref_client(SilcClient client, SilcClientConnection conn,
 210                             SilcClientEntry client_entry);
 211
 212 /****f* silcclient/SilcClientAPI/silc_client_unref_client
 213  *
 214  * SYNOPSIS
 215  *
 216  *    void silc_client_unref_client(SilcClient client,
 217  *                                  SilcClientConnection conn,
 218  *                                  SilcClientEntry client_entry);
 219  *
 220  * DESCRIPTION
 221  *
 222  *    Releases the client entry reference indicated by `client_entry'.
 223  *
 224  ***/
 225 void silc_client_unref_client(SilcClient client, SilcClientConnection conn,
 226                               SilcClientEntry client_entry);
 227
 228 /****f* silcclient/SilcClientAPI/silc_client_list_free
 229  *
 230  * SYNOPSIS
 231  *
 232  *    void silc_client_list_free(SilcClient client,
 233  *                               SilcClientConnection conn,
 234  *                               SilcDList client_list);
 235  *
 236  * DESCRIPTION
 237  *
 238  *    Free's client entry list that has been returned by various library
 239  *    routines.
 240  *
 241  ***/
 242 void silc_client_list_free(SilcClient client, SilcClientConnection conn,
 243                            SilcDList client_list);
 244
 245 /****f* silcclient/SilcClientAPI/silc_client_get_clients
 246  *
 247  * SYNOPSIS
 248  *
 249  *    SilcUInt16 silc_client_get_clients(SilcClient client,
 250  *                                       SilcClientConnection conn,
 251  *                                       const char *nickname,
 252  *                                       const char *server,
 253  *                                       SilcGetClientCallback completion,
 254  *                                       void *context);
 255  *
 256  * DESCRIPTION
 257  *
 258  *    Finds client entry or entries by the `nickname' and `server'. The
 259  *    completion callback will be called when the client entries has been
 260  *    found.  After the server returns the client information it is cached
 261  *    and can be accesses locally at a later time.  The resolving is done
 262  *    with IDENTIFY command.  The `server' may be NULL.  Returns 0 on
 263  *    error and the command identifier used with the command otherwise.
 264  *
 265  * NOTES
 266  *
 267  *    This function is always asynchronous and resolves the client
 268  *    information from the server.  Thus, if you already know the client
 269  *    information then use the silc_client_get_client_by_id function to
 270  *    get the client entry since this function may be very slow and should
 271  *    be used only to initially get the client entries.
 272  *
 273  *    This function resolves only the relevant information (user's nickname
 274  *    and username).  It does not resolve for example user's real name,
 275  *    joined channel list or other information.  To resolve all the details
 276  *    use silc_client_get_clients_whois instead.
 277  *
 278  ***/
 279 SilcUInt16 silc_client_get_clients(SilcClient client,
 280                                    SilcClientConnection conn,
 281                                    const char *nickname,
 282                                    const char *server,
 283                                    SilcGetClientCallback completion,
 284                                    void *context);
 285
 286 /****f* silcclient/SilcClientAPI/silc_client_get_clients_whois
 287  *
 288  * SYNOPSIS
 289  *
 290  *    SilcUInt16
 291  *    silc_client_get_clients_whois(SilcClient client,
 292  *                                  SilcClientConnection conn,
 293  *                                  const char *nickname,
 294  *                                  const char *server,
 295  *                                  SilcBuffer attributes,
 296  *                                  SilcGetClientCallback completion,
 297  *                                  void *context);
 298  *
 299  * DESCRIPTION
 300  *
 301  *    Finds client entry or entries by the `nickname' and `server'. The
 302  *    completion callback will be called when the client entries has been
 303  *    found.  After the server returns the client information it is cached
 304  *    and can be accesses locally at a later time.  The resolving is done
 305  *    with WHOIS command.  The `server' may be NULL.  Returns 0 on error,
 306  *    and the command identifier used with the command otherwise.
 307  *
 308  *    If the `attributes' is non-NULL then the buffer includes Requested
 309  *    Attributes which can be used to fetch very detailed information
 310  *    about the user. If it is NULL then only normal WHOIS query is
 311  *    made (for more information about attributes see SilcAttribute).
 312  *    Caller may create the `attributes' with silc_client_attributes_request
 313  *    function.
 314  *
 315  * NOTES
 316  *
 317  *    The resolving is done with WHOIS command.  For this reason this
 318  *    command may take a long time because it resolves detailed user
 319  *    information.
 320  *
 321  ***/
 322 SilcUInt16 silc_client_get_clients_whois(SilcClient client,
 323                                          SilcClientConnection conn,
 324                                          const char *nickname,
 325                                          const char *server,
 326                                          SilcBuffer attributes,
 327                                          SilcGetClientCallback completion,
 328                                          void *context);
 329
 330 /****f* silcclient/SilcClientAPI/silc_client_get_clients_local
 331  *
 332  * SYNOPSIS
 333  *
 334  *    SilcDList silc_client_get_clients_local(SilcClient client,
 335  *                                            SilcClientConnection conn,
 336  *                                            const char *nickname,
 337  *                                            const char *format);
 338  *
 339  * DESCRIPTION
 340  *
 341  *    Same as silc_client_get_clients function but does not resolve anything
 342  *    from the server.  This checks local cache and returns all matching
 343  *    clients from the local cache.  If none was found this returns NULL.
 344  *    The `nickname' is the real nickname of the client, and the `format'
 345  *    is the formatted nickname to find exact match from multiple found
 346  *    entries.  The format must be same as given in the SilcClientParams
 347  *    structure to the client library.  If the `format' is NULL all found
 348  *    clients by `nickname' are returned.  The caller must free the
 349  *    returned list by silc_client_list_free function.
 350  *
 351  * NOTES
 352  *
 353  *    If the application stores any of the SilcClientEntry pointers from
 354  *    the returned list it must reference it with silc_client_ref_client
 355  *    function.
 356  *
 357  *    Application must free the returned list with silc_client_list_free
 358  *    function.
 359  *
 360  ***/
 361 SilcDList silc_client_get_clients_local(SilcClient client,
 362                                         SilcClientConnection conn,
 363                                         const char *nickname,
 364                                         const char *format);
 365
 366 /****f* silcclient/SilcClientAPI/silc_client_get_clients_by_channel
 367  *
 368  * SYNOPSIS
 369  *
 370  *    void silc_client_get_clients_by_channel(SilcClient client,
 371  *                                            SilcClientConnection conn,
 372  *                                            SilcChannelEntry channel,
 373  *                                            SilcGetClientCallback completion,
 374  *                                            void *context);
 375  *
 376  * DESCRIPTION
 377  *
 378  *    Gets client entries by the channel indicated by `channel'. Thus,
 379  *    it resovles the users currently on that channel. If all users are
 380  *    already resolved this returns the users from the channel. If the
 381  *    users are resolved only partially this resolves the complete user
 382  *    information. If no users are resolved on this channel at all, this
 383  *    calls USERS command to resolve all users on the channel. The `completion'
 384  *    will be called after the entries are available. When server returns
 385  *    the client information it will be cached and can be accessed locally
 386  *    at a later time.
 387  *
 388  *    This function can be used for example in SILC_COMMAND_JOIN command
 389  *    reply handling in application to resolve users on that channel.  It
 390  *    also can be used after calling silc_client_get_channel_resolve to
 391  *    resolve users on that channel.
 392  *
 393  * NOTES
 394  *
 395  *    The resolving is done with WHOIS command.  For this reason this
 396  *    command may take a long time because it resolves detailed user
 397  *    information.
 398  *
 399  ***/
 400 void silc_client_get_clients_by_channel(SilcClient client,
 401                                         SilcClientConnection conn,
 402                                         SilcChannelEntry channel,
 403                                         SilcGetClientCallback completion,
 404                                         void *context);
 405
 406 /****f* silcclient/SilcClientAPI/silc_client_get_clients_by_list
 407  *
 408  * SYNOPSIS
 409  *
 410  *    void silc_client_get_clients_by_list(SilcClient client,
 411  *                                         SilcClientConnection conn,
 412  *                                         SilcUInt32 list_count,
 413  *                                         SilcBuffer client_id_list,
 414  *                                         SilcGetClientCallback completion,
 415  *                                         void *context);
 416  *
 417  * DESCRIPTION
 418  *
 419  *    Gets client entries by the list of client ID's `client_id_list'. This
 420  *    always resolves those client ID's it doesn't know about from the server.
 421  *    The `client_id_list' is a list of ID Payloads added one after other.
 422  *    JOIN command reply and USERS command reply for example returns this sort
 423  *    of list. The `completion' will be called after the entries are available.
 424  *    When server returns the client information it will be cached and can be
 425  *    accessed locally at a later time.  The resolving is done with WHOIS
 426  *    command.
 427  *
 428  * NOTES
 429  *
 430  *    If even after resolving some Client ID in the `client_id_list' is
 431  *    unknown it will be ignored and error is not returned.
 432  *
 433  ***/
 434 void silc_client_get_clients_by_list(SilcClient client,
 435                                      SilcClientConnection conn,
 436                                      SilcUInt32 list_count,
 437                                      SilcBuffer client_id_list,
 438                                      SilcGetClientCallback completion,
 439                                      void *context);
 440
 441 /****f* silcclient/SilcClientAPI/silc_client_get_client_by_id
 442  *
 443  * SYNOPSIS
 444  *
 445  *    SilcClientEntry silc_client_get_client_by_id(SilcClient client,
 446  *                                                 SilcClientConnection conn,
 447  *                                                 SilcClientID *client_id);
 448  *
 449  * DESCRIPTION
 450  *
 451  *    Find client entry by the client's ID.  Returns the entry or NULL
 452  *    if the entry was not found.  This checks the local cache and does
 453  *    not resolve anything from server.
 454  *
 455  * NOTES
 456  *
 457  *    The returned SilcClientEntry has been referenced by the library and
 458  *    the caller must call silc_client_unref_client after the entry is not
 459  *    needed anymore.
 460  *
 461  ***/
 462 SilcClientEntry silc_client_get_client_by_id(SilcClient client,
 463                                              SilcClientConnection conn,
 464                                              SilcClientID *client_id);
 465
 466 /****f* silcclient/SilcClientAPI/silc_client_get_client_by_id_resolve
 467  *
 468  * SYNOPSIS
 469  *
 470  *    void
 471  *    silc_client_get_client_by_id_resolve(SilcClient client,
 472  *                                         SilcClientConnection conn,
 473  *                                         SilcClientID *client_id,
 474  *                                         SilcBuffer attributes,
 475  *                                         SilcGetClientCallback completion,
 476  *                                         void *context);
 477  *
 478  * DESCRIPTION
 479  *
 480  *    Same as silc_client_get_client_by_id but will always resolve the
 481  *    information from the server. Use this only if you know that you
 482  *    do not have the entry and the only thing you know about the client
 483  *    is its ID. When server returns the client information it will be
 484  *    cache and can be accessed locally at a later time. The resolving
 485  *    is done by sending WHOIS command.
 486  *
 487  *    If the `attributes' is non-NULL then the buffer includes Requested
 488  *    Attributes which can be used to fetch very detailed information
 489  *    about the user. If it is NULL then only normal WHOIS query is
 490  *    made (for more information about attributes see SilcAttribute).
 491  *    Caller may create the `attributes' with silc_client_attributes_request
 492  *    function.
 493  *
 494  ***/
 495 void silc_client_get_client_by_id_resolve(SilcClient client,
 496                                           SilcClientConnection conn,
 497                                           SilcClientID *client_id,
 498                                           SilcBuffer attributes,
 499                                           SilcGetClientCallback completion,
 500                                           void *context);
 501
 502 /****f* silcclient/SilcClientAPI/silc_client_del_client
 503  *
 504  * SYNOPSIS
 505  *
 506  *    SilcBool silc_client_del_client(SilcClient client, SilcClientConnection conn,
 507  *                                SilcClientEntry client_entry)
 508  *
 509  * DESCRIPTION
 510  *
 511  *    Removes client from local cache by the client entry indicated by
 512  *    the `client_entry'.  Returns TRUE if the deletion were successful.
 513  *
 514  ***/
 515 SilcBool silc_client_del_client(SilcClient client, SilcClientConnection conn,
 516                                 SilcClientEntry client_entry);
 517
 518
 519 #endif /* SILCCLIENT_ENTRY_H */