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