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