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