lib/silcclient/silcclient_entry.h

   1 /*
   2
   3   silcclient_entry.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2006 - 2007 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 /****h* silcclient/Client Library Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * This header file includes the SilcClientEntry, SilcChannelEntry and
  25  * SilcServer entry structures and various routines to search, resolve and
  26  * handle these structures.
  27  *
  28  * All entries (SilcClientEntry, SilcChannelEntry and SilcServerEntry) are
  29  * reference counted.  If application wishes to save an entry pointer it must
  30  * always first acquire a reference.  The reference must be released once the
  31  * entry is not needed anymore.  If application wants to read any data from
  32  * the entry structure it must first lock the entry.  This protects access to
  33  * the entries in multithreaded environment.  If threads are not used, locking
  34  * the entries is not needed.  They however still must be referenced even
  35  * when threads are not used.
  36  *
  37  ***/
  38
  39 #ifndef SILCCLIENT_ENTRY_H
  40 #define SILCCLIENT_ENTRY_H
  41
  42 #ifndef SILCCLIENT_H
  43 #error "Do not include this header directly, include silcclient.h instead"
  44 #endif
  45
  46 /****s* silcclient/SilcClientAPI/SilcClientEntry
  47  *
  48  * NAME
  49  *
  50  *    typedef struct SilcClientEntryStruct { ... } *SilcClientEntry;
  51  *
  52  * DESCRIPTION
  53  *
  54  *    This structure represents a client or a user in the SILC network.
  55  *    The local user has this structure also and it can be accessed from
  56  *    SilcClientConnection structure.  All other users in the SILC network
  57  *    that are accessed using the Client Library routines will have their
  58  *    own SilcClientEntry structure.  For example, when finding users by
  59  *    their nickname the Client Library returns this structure back to
  60  *    the application.  All strings in the structure are UTF-8 encoded.
  61  *
  62  *    Application may store its own pointer into the context pointer in
  63  *    this structure.
  64  *
  65  * NOTES
  66  *
  67  *    If application wants to store nickname or any of the other strings
  68  *    it should always duplicated them.
  69  *
  70  *    None of the string arrays are set if the first character is '\0'.
  71  *    All string arrays are always zero ('\0') terminated.
  72  *
  73  *    If application stores the SilcClientEntry it must always take
  74  *    a reference of it by calling silc_client_ref_client function.  The
  75  *    reference must be released after it is not needed anymore by calling
  76  *    silc_client_unref_client function.
  77  *
  78  * SOURCE
  79  */
  80 struct SilcClientEntryStruct {
  81   char nickname[128 + 1];            /* Nickname */
  82   char username[128 + 1];            /* Username */
  83   char hostname[256 + 1];            /* Hostname */
  84   char server  [256 + 1];            /* SILC server name */
  85   char *realname;                    /* Realname (userinfo) */
  86   char *nickname_normalized;         /* Normalized nickname */
  87
  88   SilcClientID id;                   /* The Client ID */
  89   SilcUInt32 mode;                   /* User mode in SILC, see SilcUserMode */
  90   SilcPublicKey public_key;          /* User's public key, may be NULL */
  91   SilcHashTable channels;            /* Channels client has joined */
  92   SilcDList attrs;                   /* Requested Attributes (maybe NULL) */
  93   unsigned char fingerprint[20];     /* SHA-1 fingerprint of the public key */
  94
  95   void *context;                     /* Application specific context */
  96   SilcClientEntryInternal internal;
  97 };
  98 /***/
  99
 100 /****s* silcclient/SilcClientAPI/SilcChannelEntry
 101  *
 102  * NAME
 103  *
 104  *    typedef struct SilcChannelEntryStruct { ... } *SilcChannelEntry;
 105  *
 106  * DESCRIPTION
 107  *
 108  *    This structure represents a channel in the SILC network.  All
 109  *    channels that the client are aware of or have joined in will be
 110  *    represented as SilcChannelEntry.  The structure includes information
 111  *    about the channel.  All strings in the structure are UTF-8 encoded.
 112  *
 113  *    Application may store its own pointer into the context pointer in
 114  *    this structure.
 115  *
 116  * NOTES
 117  *
 118  *    If application stores the SilcChannelEntry it must always take
 119  *    a reference of it by calling silc_client_ref_channel function.  The
 120  *    reference must be released after it is not needed anymore by calling
 121  *    silc_client_unref_channel function.
 122  *
 123  * SOURCE
 124  */
 125 struct SilcChannelEntryStruct {
 126   char *channel_name;                /* Channel name */
 127   char *topic;                       /* Current topic, may be NULL */
 128   SilcPublicKey founder_key;         /* Founder key, may be NULL */
 129   SilcDList channel_pubkeys;         /* Channel public keys, may be NULL */
 130   SilcChannelID id;                  /* Channel ID */
 131   SilcUInt32 mode;                   /* Channel mode, ChannelModes. */
 132   SilcUInt32 user_limit;             /* User limit on channel */
 133   SilcHashTable user_list;           /* Joined users.  Key to hash table is
 134                                         SilcClientEntry, context is
 135                                         SilcChannelUser. */
 136   const char *cipher;                /* Current channel cipher algorithm*/
 137   const char *hmac;                  /* Current channel HMAC algorithm */
 138
 139   void *context;                     /* Application specific context */
 140   SilcChannelEntryInternal internal;
 141 };
 142 /***/
 143
 144 /****s* silcclient/SilcClientAPI/SilcServerEntry
 145  *
 146  * NAME
 147  *
 148  *    typedef struct SilcServerEntryStruct { ... } *SilcServerEntry;
 149  *
 150  * DESCRIPTION
 151  *
 152  *    This structure represents a server in the SILC network.  All servers
 153  *    that the client is aware of and have for example resolved with
 154  *    SILC_COMMAND_INFO command have their on SilcServerEntry structure.
 155  *    Server's public key is present only if it has been retrieved using
 156  *    SILC_COMMAND_GETKEY command.  All strings in the structure are UTF-8
 157  *    encoded.
 158  *
 159  *    Application may store its own pointer into the context pointer in
 160  *    this structure.
 161  *
 162  * NOTES
 163  *
 164  *    If application stores the SilcServerEntry it must always take
 165  *    a reference of it by calling silc_client_ref_server function.  The
 166  *    reference must be released after it is not needed anymore by calling
 167  *    silc_client_unref_server function.
 168  *
 169  * SOURCE
 170  */
 171 struct SilcServerEntryStruct {
 172   /* General information */
 173   char *server_name;                 /* Server name */
 174   char *server_info;                 /* Server info */
 175   SilcServerID id;                   /* Server ID */
 176   SilcPublicKey public_key;          /* Server public key, may be NULL */
 177
 178   void *context;                     /* Application specific context */
 179   SilcServerEntryInternal internal;
 180 };
 181 /***/
 182
 183 /* SilcClientEntry routines */
 184
 185 /****f* silcclient/SilcClientAPI/SilcGetClientCallback
 186  *
 187  * SYNOPSIS
 188  *
 189  *    typedef void (*SilcGetClientCallback)(SilcClient client,
 190  *                                          SilcClientConnection conn,
 191  *                                          SilcStatus status,
 192  *                                          SilcDList clients,
 193  *                                          void *context);
 194  *
 195  * DESCRIPTION
 196  *
 197  *    Callback function given to various client search functions.  The
 198  *    found entries are allocated into the `clients' list.  The list must
 199  *    not be freed by the receiver, the library will free it later.  If the
 200  *    `clients' is NULL, no such clients exist in the SILC network, and
 201  *    the `status' will include the error.  Each entry in the `clients'
 202  *    is SilcClientEntry.
 203  *
 204  * NOTES
 205  *
 206  *    If the application stores any of the SilcClientEntry pointers from
 207  *    the `clients' list it must reference it with silc_client_ref_client
 208  *    function.
 209  *
 210  *    Application must not free the returned `clients' list.
 211  *
 212  ***/
 213 typedef void (*SilcGetClientCallback)(SilcClient client,
 214                                       SilcClientConnection conn,
 215                                       SilcStatus status,
 216                                       SilcDList clients,
 217                                       void *context);
 218
 219 /****f* silcclient/SilcClientAPI/silc_client_lock_client
 220  *
 221  * SYNOPSIS
 222  *
 223  *    void silc_client_lock_client(SilcClientEntry client_entry);
 224  *
 225  * DESCRIPTION
 226  *
 227  *    Acquires lock for the client entry indicate by `client_entry'.  When
 228  *    application wants to access `client_entry' it must lock the entry
 229  *    before reading any data from the `client_entry'.  The lock must be
 230  *    unlocked with silc_client_unlock_client.
 231  *
 232  * NOTES
 233  *
 234  *    The entry must be unlocked before calling any Client Library API
 235  *    functions where the entry is given as argument, unless otherwise stated.
 236  *
 237  *    The entry should not be locked for long periods of time.  For example,
 238  *    it is not appropriate to hold the lock while waiting user interface to
 239  *    be drawn.  The appropriate way is to read the data and duplicate it if
 240  *    necessary, unlock the entry, then draw on the user interface.
 241  *
 242  *    This function is not needed if application is not multithreaded.
 243  *
 244  ***/
 245 void silc_client_lock_client(SilcClientEntry client_entry);
 246
 247 /****f* silcclient/SilcClientAPI/silc_client_unlock_client
 248  *
 249  * SYNOPSIS
 250  *
 251  *    void silc_client_unlock_client(SilcClientEntry client_entry);
 252  *
 253  * DESCRIPTION
 254  *
 255  *    Releases the lock acquired with silc_client_lock_client.
 256  *
 257  ***/
 258 void silc_client_unlock_client(SilcClientEntry client_entry);
 259
 260 /****f* silcclient/SilcClientAPI/silc_client_ref_client
 261  *
 262  * SYNOPSIS
 263  *
 264  *    SilcClientEntry
 265  *    silc_client_ref_client(SilcClient client,
 266  *                           SilcClientConnection conn,
 267  *                           SilcClientEntry client_entry);
 268  *
 269  * DESCRIPTION
 270  *
 271  *    Takes a reference of the client entry indicated by `client_entry'
 272  *    The reference must be released by calling silc_client_unref_client
 273  *    after it is not needed anymore.  Returns `client_entry'.
 274  *
 275  ***/
 276 SilcClientEntry silc_client_ref_client(SilcClient client,
 277                                        SilcClientConnection conn,
 278                                        SilcClientEntry client_entry);
 279
 280 /****f* silcclient/SilcClientAPI/silc_client_unref_client
 281  *
 282  * SYNOPSIS
 283  *
 284  *    void silc_client_unref_client(SilcClient client,
 285  *                                  SilcClientConnection conn,
 286  *                                  SilcClientEntry client_entry);
 287  *
 288  * DESCRIPTION
 289  *
 290  *    Releases the client entry reference indicated by `client_entry'.
 291  *
 292  ***/
 293 void silc_client_unref_client(SilcClient client, SilcClientConnection conn,
 294                               SilcClientEntry client_entry);
 295
 296 /****f* silcclient/SilcClientAPI/silc_client_list_free
 297  *
 298  * SYNOPSIS
 299  *
 300  *    void silc_client_list_free(SilcClient client,
 301  *                               SilcClientConnection conn,
 302  *                               SilcDList client_list);
 303  *
 304  * DESCRIPTION
 305  *
 306  *    Free's client entry list that has been returned by various library
 307  *    routines.
 308  *
 309  ***/
 310 void silc_client_list_free(SilcClient client, SilcClientConnection conn,
 311                            SilcDList client_list);
 312
 313 /****f* silcclient/SilcClientAPI/silc_client_get_clients
 314  *
 315  * SYNOPSIS
 316  *
 317  *    SilcUInt16 silc_client_get_clients(SilcClient client,
 318  *                                       SilcClientConnection conn,
 319  *                                       const char *nickname,
 320  *                                       const char *server,
 321  *                                       SilcGetClientCallback completion,
 322  *                                       void *context);
 323  *
 324  * DESCRIPTION
 325  *
 326  *    Finds client entry or entries by the `nickname' and `server'. The
 327  *    completion callback will be called when the client entries has been
 328  *    found.  After the server returns the client information it is cached
 329  *    and can be accesses locally at a later time.  The resolving is done
 330  *    with IDENTIFY command.  The `server' may be NULL.  The server
 331  *    associated with the nickname may be in the `nickname' (nick@server).
 332  *    The `nickname' may also be a formatted nickname in which case the
 333  *    formatting is ignored and the base nickname is used.  If the nickname
 334  *    is formatted it must be formatted as defined in SilcClientParams.
 335  *    Returns 0 on error and the command identifier used with the command
 336  *    otherwise.
 337  *
 338  * NOTES
 339  *
 340  *    This function is always asynchronous and resolves the client
 341  *    information from the server.  Thus, if you already know the client
 342  *    information then use the silc_client_get_client_by_id function to
 343  *    get the client entry since this function may be very slow and should
 344  *    be used only to initially get the client entries.
 345  *
 346  *    This function resolves only the relevant information (user's nickname
 347  *    and username).  It does not resolve for example user's real name,
 348  *    joined channel list or other information.  To resolve all the details
 349  *    use silc_client_get_clients_whois instead.
 350  *
 351  ***/
 352 SilcUInt16 silc_client_get_clients(SilcClient client,
 353                                    SilcClientConnection conn,
 354                                    const char *nickname,
 355                                    const char *server,
 356                                    SilcGetClientCallback completion,
 357                                    void *context);
 358
 359 /****f* silcclient/SilcClientAPI/silc_client_get_clients_whois
 360  *
 361  * SYNOPSIS
 362  *
 363  *    SilcUInt16
 364  *    silc_client_get_clients_whois(SilcClient client,
 365  *                                  SilcClientConnection conn,
 366  *                                  const char *nickname,
 367  *                                  const char *server,
 368  *                                  SilcBuffer attributes,
 369  *                                  SilcGetClientCallback completion,
 370  *                                  void *context);
 371  *
 372  * DESCRIPTION
 373  *
 374  *    Finds client entry or entries by the `nickname' and `server'. The
 375  *    completion callback will be called when the client entries has been
 376  *    found.  After the server returns the client information it is cached
 377  *    and can be accesses locally at a later time.  The resolving is done
 378  *    with WHOIS command.  The `server' may be NULL.  The server
 379  *    associated with the nickname may be in the `nickname' (nick@server).
 380  *    The `nickname' may also be a formatted nickname in which case the
 381  *    formatting is ignored and the base nickname is used.  If the nickname
 382  *    is formatted it must be formatted as defined in SilcClientParams.
 383  *    Returns 0 on error and the command identifier used with the command
 384  *    otherwise.
 385  *
 386  *    If the `attributes' is non-NULL then the buffer includes Requested
 387  *    Attributes which can be used to fetch very detailed information
 388  *    about the user. If it is NULL then only normal WHOIS query is
 389  *    made (for more information about attributes see SilcAttribute).
 390  *    Caller may create the `attributes' with silc_client_attributes_request
 391  *    function.
 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 SilcUInt16 silc_client_get_clients_whois(SilcClient client,
 401                                          SilcClientConnection conn,
 402                                          const char *nickname,
 403                                          const char *server,
 404                                          SilcBuffer attributes,
 405                                          SilcGetClientCallback completion,
 406                                          void *context);
 407
 408 /****f* silcclient/SilcClientAPI/silc_client_get_clients_local
 409  *
 410  * SYNOPSIS
 411  *
 412  *    SilcDList silc_client_get_clients_local(SilcClient client,
 413  *                                            SilcClientConnection conn,
 414  *                                            const char *nickname,
 415  *                                            SilcBool return_all);
 416  *
 417  * DESCRIPTION
 418  *
 419  *    Same as silc_client_get_clients function but does not resolve anything
 420  *    from the server.  This checks local cache and returns matching clients
 421  *    from the local cache.  If none was found this returns NULL.  The
 422  *    `nickname' is the nickname to find and it may be a formatted nickname
 423  *    or a base nickname.  If the `return_all' is TRUE this call will return
 424  *    all clients matching the `nickname' base.  If it is FALSE this will
 425  *    return the exact match if `nickname' is a formatted nickname or the
 426  *    first matching nickname if it is not formatted.  The formatted nickname
 427  *    must of the format specified in SilcClientParams.  The caller must free
 428  *    the returned list by calling silc_client_list_free function.
 429  *
 430  * NOTES
 431  *
 432  *    If the application stores any of the SilcClientEntry pointers from
 433  *    the returned list it must reference it with silc_client_ref_client
 434  *    function.
 435  *
 436  *    Application must free the returned list with silc_client_list_free
 437  *    function.
 438  *
 439  ***/
 440 SilcDList silc_client_get_clients_local(SilcClient client,
 441                                         SilcClientConnection conn,
 442                                         const char *nickname,
 443                                         SilcBool return_all);
 444
 445 /****f* silcclient/SilcClientAPI/silc_client_get_clients_by_channel
 446  *
 447  * SYNOPSIS
 448  *
 449  *    void silc_client_get_clients_by_channel(SilcClient client,
 450  *                                            SilcClientConnection conn,
 451  *                                            SilcChannelEntry channel,
 452  *                                            SilcGetClientCallback completion,
 453  *                                            void *context);
 454  *
 455  * DESCRIPTION
 456  *
 457  *    Gets client entries by the channel indicated by `channel'. Thus,
 458  *    it resovles the users currently on that channel. If all users are
 459  *    already resolved this returns the users from the channel. If the
 460  *    users are resolved only partially this resolves the complete user
 461  *    information. If no users are resolved on this channel at all, this
 462  *    calls USERS command to resolve all users on the channel. The `completion'
 463  *    will be called after the entries are available. When server returns
 464  *    the client information it will be cached and can be accessed locally
 465  *    at a later time.
 466  *
 467  *    This function can be used for example in SILC_COMMAND_JOIN command
 468  *    reply handling in application to resolve users on that channel.  It
 469  *    also can be used after calling silc_client_get_channel_resolve to
 470  *    resolve users on that channel.
 471  *
 472  * NOTES
 473  *
 474  *    The resolving is done with WHOIS command.  For this reason this
 475  *    command may take a long time because it resolves detailed user
 476  *    information.
 477  *
 478  ***/
 479 void silc_client_get_clients_by_channel(SilcClient client,
 480                                         SilcClientConnection conn,
 481                                         SilcChannelEntry channel,
 482                                         SilcGetClientCallback completion,
 483                                         void *context);
 484
 485 /****f* silcclient/SilcClientAPI/silc_client_get_client_by_id
 486  *
 487  * SYNOPSIS
 488  *
 489  *    SilcClientEntry silc_client_get_client_by_id(SilcClient client,
 490  *                                                 SilcClientConnection conn,
 491  *                                                 SilcClientID *client_id);
 492  *
 493  * DESCRIPTION
 494  *
 495  *    Find client entry by the client's ID.  Returns the entry or NULL
 496  *    if the entry was not found.  This checks the local cache and does
 497  *    not resolve anything from server.
 498  *
 499  * NOTES
 500  *
 501  *    The returned SilcClientEntry has been referenced by the library and
 502  *    the caller must call silc_client_unref_client after the entry is not
 503  *    needed anymore.
 504  *
 505  ***/
 506 SilcClientEntry silc_client_get_client_by_id(SilcClient client,
 507                                              SilcClientConnection conn,
 508                                              SilcClientID *client_id);
 509
 510 /****f* silcclient/SilcClientAPI/silc_client_get_client_by_id_resolve
 511  *
 512  * SYNOPSIS
 513  *
 514  *    SilcUInt16
 515  *    silc_client_get_client_by_id_resolve(SilcClient client,
 516  *                                         SilcClientConnection conn,
 517  *                                         SilcClientID *client_id,
 518  *                                         SilcBuffer attributes,
 519  *                                         SilcGetClientCallback completion,
 520  *                                         void *context);
 521  *
 522  * DESCRIPTION
 523  *
 524  *    Same as silc_client_get_client_by_id but will always resolve the
 525  *    information from the server. Use this only if you know that you
 526  *    do not have the entry and the only thing you know about the client
 527  *    is its ID. When server returns the client information it will be
 528  *    cache and can be accessed locally at a later time. The resolving
 529  *    is done by sending WHOIS command.
 530  *
 531  *    Returns command identifier for the resolving.  It can be used to attach
 532  *    a pending command to it, if needed.  Returns 0 on error.
 533  *
 534  *    If the `attributes' is non-NULL then the buffer includes Requested
 535  *    Attributes which can be used to fetch very detailed information
 536  *    about the user. If it is NULL then only normal WHOIS query is
 537  *    made (for more information about attributes see SilcAttribute).
 538  *    Caller may create the `attributes' with silc_client_attributes_request
 539  *    function.
 540  *
 541  ***/
 542 SilcUInt16
 543 silc_client_get_client_by_id_resolve(SilcClient client,
 544                                      SilcClientConnection conn,
 545                                      SilcClientID *client_id,
 546                                      SilcBuffer attributes,
 547                                      SilcGetClientCallback completion,
 548                                      void *context);
 549
 550 /* SilcChannelEntry routines */
 551
 552 /****f* silcclient/SilcClientAPI/SilcGetChannelCallback
 553  *
 554  * SYNOPSIS
 555  *
 556  *    typedef void (*SilcGetChannelCallback)(SilcClient client,
 557  *                                           SilcClientConnection conn,
 558  *                                           SilcStatus status,
 559  *                                           SilcDList channels,
 560  *                                           void *context);
 561  *
 562  * DESCRIPTION
 563  *
 564  *    Callback function given to various channel resolving functions.
 565  *    The found entries are included in the `channels' list and each entry
 566  *    in the list is SilcChannelEntry.  If `channels' is NULL then no such
 567  *    channel exist in the network and the `status' will indicate the error.
 568  *
 569  * NOTES
 570  *
 571  *    If the application stores any of the SilcChannelEntry pointers from
 572  *    the `channels' list it must reference it with silc_client_ref_channel
 573  *    function.
 574  *
 575  *    Application must not free the returned `channels' list.
 576  *
 577  ***/
 578 typedef void (*SilcGetChannelCallback)(SilcClient client,
 579                                        SilcClientConnection conn,
 580                                        SilcStatus status,
 581                                        SilcDList channels,
 582                                        void *context);
 583
 584 /****f* silcclient/SilcClientAPI/silc_client_lock_channel
 585  *
 586  * SYNOPSIS
 587  *
 588  *    void silc_client_lock_channel(SilcChannelEntry channel_entry);
 589  *
 590  * DESCRIPTION
 591  *
 592  *    Acquires lock for the channel entry indicate by `channel_entry'.  When
 593  *    application wants to access `channel_entry' it must lock the entry
 594  *    before reading any data from the `channel_entry'.  The lock must be
 595  *    unlocked with silc_client_unlock_channel.
 596  *
 597  * NOTES
 598  *
 599  *    The entry must be unlocked before calling any Client Library API
 600  *    functions where the entry is given as argument, unless otherwise stated.
 601  *
 602  *    The entry should not be locked for long periods of time.  For example,
 603  *    it is not appropriate to hold the lock while waiting user interface to
 604  *    be drawn.  The appropriate way is to read the data and duplicate it if
 605  *    necessary, unlock the entry, then draw on the user interface.
 606  *
 607  *    This function is not needed if application is not multithreaded.
 608  *
 609  ***/
 610 void silc_client_lock_channel(SilcChannelEntry channel_entry);
 611
 612 /****f* silcclient/SilcClientAPI/silc_client_unlock_channel
 613  *
 614  * SYNOPSIS
 615  *
 616  *    void silc_client_unlock_channel(SilcChannelEntry channel_entry);
 617  *
 618  * DESCRIPTION
 619  *
 620  *    Releases the lock acquired with silc_client_lock_channel.
 621  *
 622  ***/
 623 void silc_client_unlock_channel(SilcChannelEntry channel_entry);
 624
 625 /****f* silcclient/SilcClientAPI/silc_client_ref_channel
 626  *
 627  * SYNOPSIS
 628  *
 629  *    SilcChannelEntry
 630  *    silc_client_ref_channel(SilcClient client,
 631  *                            SilcClientConnection conn,
 632  *                            SilcChannelEntry channel_entry);
 633  *
 634  * DESCRIPTION
 635  *
 636  *    Takes a reference of the channel entry indicated by `channel_entry'
 637  *    The reference must be released by calling silc_client_unref_channel
 638  *    after it is not needed anymore.  Returns `channel_entry'.
 639  *
 640  ***/
 641 SilcChannelEntry silc_client_ref_channel(SilcClient client,
 642                                          SilcClientConnection conn,
 643                                          SilcChannelEntry channel_entry);
 644
 645 /****f* silcclient/SilcClientAPI/silc_client_unref_channel
 646  *
 647  * SYNOPSIS
 648  *
 649  *    void silc_client_unref_channel(SilcClient client,
 650  *                                   SilcClientConnection conn,
 651  *                                   SilcChannelEntry channel_entry);
 652  *
 653  * DESCRIPTION
 654  *
 655  *    Releases the channel entry reference indicated by `channel_entry'.
 656  *
 657  ***/
 658 void silc_client_unref_channel(SilcClient client, SilcClientConnection conn,
 659                                SilcChannelEntry channel_entry);
 660
 661 /****f* silcclient/SilcClientAPI/silc_client_list_free_channel
 662  *
 663  * SYNOPSIS
 664  *
 665  *    void silc_client_list_free_channel(SilcClient client,
 666  *                                       SilcClientConnection conn,
 667  *                                       SilcDList channel_list);
 668  *
 669  * DESCRIPTION
 670  *
 671  *    Free's channel entry list that has been returned by various library
 672  *    routines.
 673  *
 674  ***/
 675 void silc_client_list_free_channels(SilcClient client,
 676                                     SilcClientConnection conn,
 677                                     SilcDList channel_list);
 678
 679 /****f* silcclient/SilcClientAPI/silc_client_get_channel
 680  *
 681  * SYNOPSIS
 682  *
 683  *    SilcChannelEntry silc_client_get_channel(SilcClient client,
 684  *                                             SilcClientConnection conn,
 685  *                                             char *channel_name);
 686  *
 687  * DESCRIPTION
 688  *
 689  *    Finds entry for channel by the channel name. Returns the entry or NULL
 690  *    if the entry was not found. It is found only if the client is joined
 691  *    to the channel.  Use silc_client_get_channel_resolve or
 692  *    silc_client_get_channel_by_id_resolve to resolve channel that client
 693  *    is not joined.
 694  *
 695  * NOTES
 696  *
 697  *    The returned SilcChannelEntry has been referenced by the library and
 698  *    the caller must call silc_client_unref_channel after the entry is not
 699  *    needed anymore.
 700  *
 701  ***/
 702 SilcChannelEntry silc_client_get_channel(SilcClient client,
 703                                          SilcClientConnection conn,
 704                                          char *channel_name);
 705
 706 /****f* silcclient/SilcClientAPI/silc_client_get_channel_resolve
 707  *
 708  * SYNOPSIS
 709  *
 710  *    void silc_client_get_channel_resolve(SilcClient client,
 711  *                                         SilcClientConnection conn,
 712  *                                         char *channel_name,
 713  *                                         SilcGetChannelCallback completion,
 714  *                                         void *context);
 715  *
 716  * DESCRIPTION
 717  *
 718  *    Resolves entry for channel by the channel name from the server.
 719  *    The resolving is done with IDENTIFY command. Note that users on
 720  *    the channel are not resolved at the same time. Use for example
 721  *    silc_client_get_clients_by_channel to resolve all users on a channel.
 722  *
 723  ***/
 724 void silc_client_get_channel_resolve(SilcClient client,
 725                                      SilcClientConnection conn,
 726                                      char *channel_name,
 727                                      SilcGetChannelCallback completion,
 728                                      void *context);
 729
 730 /****f* silcclient/SilcClientAPI/silc_client_get_channel_by_id
 731  *
 732  * SYNOPSIS
 733  *
 734  *    SilcChannelEntry
 735  *    silc_client_get_channel_by_id(SilcClient client,
 736  *                                  SilcClientConnection conn,
 737  *                                  SilcChannelID *channel_id);
 738  *
 739  * DESCRIPTION
 740  *
 741  *    Finds channel entry by the channel ID. Returns the entry or NULL
 742  *    if the entry was not found.  This checks the local cache and does
 743  *    not resolve anything from server.
 744  *
 745  * NOTES
 746  *
 747  *    The returned SilcChannelEntry has been referenced by the library and
 748  *    the caller must call silc_client_unref_channel after the entry is not
 749  *    needed anymore.
 750  *
 751  ***/
 752 SilcChannelEntry silc_client_get_channel_by_id(SilcClient client,
 753                                                SilcClientConnection conn,
 754                                                SilcChannelID *channel_id);
 755
 756 /****f* silcclient/SilcClientAPI/silc_client_get_channel_by_id_resolve
 757  *
 758  * SYNOPSIS
 759  *
 760  *    SilcUInt16
 761  *    silc_client_get_channel_by_id_resolve(SilcClient client,
 762  *                                          SilcClientConnection conn,
 763  *                                          SilcChannelID *channel_id,
 764  *                                          SilcGetClientCallback completion,
 765  *                                          void *context);
 766  *
 767  * DESCRIPTION
 768  *
 769  *    Resolves the channel information (its name mainly) from the server
 770  *    by the `channel_id'. Use this only if you know that you do not have
 771  *    the entry cached locally. The resolving is done with IDENTIFY command.
 772  *
 773  *    Returns command identifier for the resolving.  It can be used to attach
 774  *    a pending command to it, if needed.  Returns 0 on error.
 775  *
 776  *    Note that users on the channel are not resolved at the same time.
 777  *    Use for example silc_client_get_clients_by_channel to resolve all
 778  *    users on a channel.
 779  *
 780  ***/
 781 SilcUInt16
 782 silc_client_get_channel_by_id_resolve(SilcClient client,
 783                                       SilcClientConnection conn,
 784                                       SilcChannelID *channel_id,
 785                                       SilcGetChannelCallback completion,
 786                                       void *context);
 787
 788 /* SilcServerEntry routines */
 789
 790 /****f* silcclient/SilcClientAPI/SilcGetServerCallback
 791  *
 792  * SYNOPSIS
 793  *
 794  *    typedef void (*SilcGetServerCallback)(SilcClient client,
 795  *                                          SilcClientConnection conn,
 796  *                                          SilcStatus status,
 797  *                                          SilcDList servers,
 798  *                                          void *context);
 799  *
 800  * DESCRIPTION
 801  *
 802  *    Callback function given to various server resolving functions.
 803  *    The found entries are included in the `servers' list and each entry
 804  *    in the list is SilcServerEntry.  If `server' is NULL then no such
 805  *    server exist in the network and the `status' will indicate the error.
 806  *
 807  * NOTES
 808  *
 809  *    If the application stores any of the SilcServerEntry pointers from
 810  *    the `server' list it must reference it with silc_client_ref_server
 811  *    function.
 812  *
 813  *    Application must not free the returned `server' list.
 814  *
 815  ***/
 816 typedef void (*SilcGetServerCallback)(SilcClient client,
 817                                       SilcClientConnection conn,
 818                                       SilcStatus status,
 819                                       SilcDList servers,
 820                                       void *context);
 821
 822 /****f* silcclient/SilcClientAPI/silc_client_lock_server
 823  *
 824  * SYNOPSIS
 825  *
 826  *    void silc_client_lock_server(SilcServerEntry server_entry);
 827  *
 828  * DESCRIPTION
 829  *
 830  *    Acquires lock for the server entry indicate by `server_entry'.  When
 831  *    application wants to access `server_entry' it must lock the entry
 832  *    before reading any data from the `server_entry'.  The lock must be
 833  *    unlocked with silc_client_unlock_server.
 834  *
 835  * NOTES
 836  *
 837  *    The entry must be unlocked before calling any Client Library API
 838  *    functions where the entry is given as argument, unless otherwise stated.
 839  *
 840  *    The entry should not be locked for long periods of time.  For example,
 841  *    it is not appropriate to hold the lock while waiting user interface to
 842  *    be drawn.  The appropriate way is to read the data and duplicate it if
 843  *    necessary, unlock the entry, then draw on the user interface.
 844  *
 845  *    This function is not needed if application is not multithreaded.
 846  *
 847  ***/
 848 void silc_client_lock_server(SilcServerEntry server_entry);
 849
 850 /****f* silcclient/SilcClientAPI/silc_client_unlock_server
 851  *
 852  * SYNOPSIS
 853  *
 854  *    void silc_client_unlock_server(SilcServerEntry server_entry);
 855  *
 856  * DESCRIPTION
 857  *
 858  *    Releases the lock acquired with silc_client_lock_server.
 859  *
 860  ***/
 861 void silc_client_unlock_server(SilcServerEntry server_entry);
 862
 863 /****f* silcclient/SilcClientAPI/silc_client_ref_server
 864  *
 865  * SYNOPSIS
 866  *
 867  *    SilcServerEntry
 868  *    silc_client_ref_server(SilcClient client,
 869  *                           SilcClientConnection conn,
 870  *                           SilcServerEntry server_entry);
 871  *
 872  * DESCRIPTION
 873  *
 874  *    Takes a reference of the server entry indicated by `server_entry'
 875  *    The reference must be released by calling silc_client_unref_server
 876  *    after it is not needed anymore.  Returns `server_entry'.
 877  *
 878  ***/
 879 SilcServerEntry silc_client_ref_server(SilcClient client,
 880                                        SilcClientConnection conn,
 881                                        SilcServerEntry server_entry);
 882
 883 /****f* silcclient/SilcClientAPI/silc_client_unref_server
 884  *
 885  * SYNOPSIS
 886  *
 887  *    void silc_client_unref_server(SilcClient client,
 888  *                                  SilcClientConnection conn,
 889  *                                  SilcServerEntry server_entry);
 890  *
 891  * DESCRIPTION
 892  *
 893  *    Releases the server entry reference indicated by `server_entry'.
 894  *
 895  ***/
 896 void silc_client_unref_server(SilcClient client, SilcClientConnection conn,
 897                               SilcServerEntry server_entry);
 898
 899 /****f* silcclient/SilcClientAPI/silc_client_list_free_server
 900  *
 901  * SYNOPSIS
 902  *
 903  *    void silc_client_list_free_server(SilcClient client,
 904  *                                      SilcClientConnection conn,
 905  *                                      SilcDList server_list);
 906  *
 907  * DESCRIPTION
 908  *
 909  *    Free's server entry list that has been returned by various library
 910  *    routines.
 911  *
 912  ***/
 913 void silc_client_list_free_servers(SilcClient client,
 914                                    SilcClientConnection conn,
 915                                    SilcDList server_list);
 916
 917 /****f* silcclient/SilcClientAPI/silc_client_get_server
 918  *
 919  * SYNOPSIS
 920  *
 921  *    SilcServerEntry silc_client_get_server(SilcClient client,
 922  *                                           SilcClientConnection conn,
 923  *                                           char *server_name)
 924  *
 925  * DESCRIPTION
 926  *
 927  *    Finds entry for server by the server name. Returns the entry or NULL
 928  *    if the entry was not found.
 929  *
 930  ***/
 931 SilcServerEntry silc_client_get_server(SilcClient client,
 932                                        SilcClientConnection conn,
 933                                        char *server_name);
 934
 935 /****f* silcclient/SilcClientAPI/silc_client_get_server_by_id
 936  *
 937  * SYNOPSIS
 938  *
 939  *    SilcServerEntry silc_client_get_server_by_id(SilcClient client,
 940  *                                                 SilcClientConnection conn,
 941  *                                                 SilcServerID *server_id);
 942  *
 943  * DESCRIPTION
 944  *
 945  *    Finds entry for server by the server ID. Returns the entry or NULL
 946  *    if the entry was not found.
 947  *
 948  ***/
 949 SilcServerEntry silc_client_get_server_by_id(SilcClient client,
 950                                              SilcClientConnection conn,
 951                                              SilcServerID *server_id);
 952
 953 /****f* silcclient/SilcClientAPI/silc_client_get_server_by_id_resolve
 954  *
 955  * SYNOPSIS
 956  *
 957  *    SilcUInt16
 958  *    silc_client_get_server_by_id_resolve(SilcClient client,
 959  *                                         SilcClientConnection conn,
 960  *                                         SilcServerID *server_id,
 961  *                                         SilcGetServerCallback completion,
 962  *                                         void *context);
 963  *
 964  * DESCRIPTION
 965  *
 966  *    Resolves the server information by the `server_id'.  The resolved
 967  *    server is returned into the `completion' callback.
 968  *
 969  *    Returns command identifier for the resolving.  It can be used to attach
 970  *    a pending command to it, if needed.  Returns 0 on error.
 971  *
 972  ***/
 973 SilcUInt16
 974 silc_client_get_server_by_id_resolve(SilcClient client,
 975                                      SilcClientConnection conn,
 976                                      SilcServerID *server_id,
 977                                      SilcGetServerCallback completion,
 978                                      void *context);
 979
 980 #endif /* SILCCLIENT_ENTRY_H */