lib/silcclient/silcclient_entry.h

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