- unsigned int key_count);
-
-
-/* Client and Channel entry retrieval */
-
-/* Callback function given to the silc_client_get_client function. The
- found entries are allocated into the `clients' array. The array must
- not be freed by the caller, the library will free it later. If the
- `clients' is NULL, no such clients exist in the SILC Network. */
-typedef void (*SilcGetClientCallback)(SilcClient client,
- SilcClientConnection conn,
- SilcClientEntry *clients,
- unsigned int clients_count,
- void *context);
-
-/* Finds client entry or entries by the `nickname' and `server'. The
- completion callback will be called when the client entries has been found.
-
- Note: this function is always asynchronous and resolves the client
- information from the server. Thus, if you already know the client
- information then use the silc_client_get_client_by_id function to
- get the client entry since this function may be very slow and should
- be used only to initially get the client entries. */
-void silc_client_get_clients(SilcClient client,
- SilcClientConnection conn,
- char *nickname,
- char *server,
- SilcGetClientCallback completion,
- void *context);
-
-/* Same as above function but does not resolve anything from the server.
- This checks local cache and returns all clients from the cache. */
-SilcClientEntry *silc_client_get_clients_local(SilcClient client,
- SilcClientConnection conn,
- char *nickname,
- char *server,
- unsigned int *clients_count);
-
-/* Find entry for client by the client's ID. Returns the entry or NULL
- if the entry was not found. */
-SilcClientEntry silc_client_get_client_by_id(SilcClient client,
- SilcClientConnection conn,
- SilcClientID *client_id);
-
-/* Finds entry for channel by the channel name. Returns the entry or NULL
- if the entry was not found. It is found only if the client is joined
- to the channel. */
-SilcChannelEntry silc_client_get_channel(SilcClient client,
- SilcClientConnection conn,
- char *channel);
+ uint32 key_count);
+
+
+/* Key Agreement routines (client_keyagr.c) */
+
+/****f* silcclient/SilcClientAPI/silc_client_send_key_agreement
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_send_key_agreement(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * char *hostname,
+ * int port,
+ * uint32 timeout_secs,
+ * SilcKeyAgreementCallback completion,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Sends key agreement request to the remote client indicated by the
+ * `client_entry'. If the caller provides the `hostname' and the `port'
+ * arguments then the library will bind the client to that hostname and
+ * that port for the key agreement protocol. It also sends the `hostname'
+ * and the `port' in the key agreement packet to the remote client. This
+ * would indicate that the remote client may initiate the key agreement
+ * protocol to the `hostname' on the `port'. If port is zero then the
+ * bound port is undefined (the operating system defines it).
+ *
+ * If the `hostname' and `port' is not provided then empty key agreement
+ * packet is sent to the remote client. The remote client may reply with
+ * the same packet including its hostname and port. If the library receives
+ * the reply from the remote client the `key_agreement' client operation
+ * callback will be called to verify whether the user wants to perform the
+ * key agreement or not.
+ *
+ * NOTES
+ *
+ * NOTE: If the application provided the `hostname' and the `port' and the
+ * remote side initiates the key agreement protocol it is not verified
+ * from the user anymore whether the protocol should be executed or not.
+ * By setting the `hostname' and `port' the user gives permission to
+ * perform the protocol (we are responder in this case).
+ *
+ * NOTE: If the remote side decides not to initiate the key agreement
+ * or decides not to reply with the key agreement packet then we cannot
+ * perform the key agreement at all. If the key agreement protocol is
+ * performed the `completion' callback with the `context' will be called.
+ * If remote side decides to ignore the request the `completion' will be
+ * called after the specified timeout, `timeout_secs'.
+ *
+ * NOTE: If the `hostname' and the `port' was not provided the `completion'
+ * will not be called at all since this does nothing more than sending
+ * a packet to the remote host.
+ *
+ * NOTE: There can be only one active key agreement for one client entry.
+ * Before setting new one, the old one must be finished (it is finished
+ * after calling the completion callback) or the function
+ * silc_client_abort_key_agreement must be called.
+ *
+ ***/
+void silc_client_send_key_agreement(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ char *hostname,
+ int port,
+ uint32 timeout_secs,
+ SilcKeyAgreementCallback completion,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_client_perform_key_agreement(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * char *hostname,
+ * int port,
+ * SilcKeyAgreementCallback completion,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Performs the actual key agreement protocol. Application may use this
+ * to initiate the key agreement protocol. This can be called for example
+ * after the application has received the `key_agreement' client operation,
+ * and did not return TRUE from it.
+ *
+ * The `hostname' is the remote hostname (or IP address) and the `port'
+ * is the remote port. The `completion' callback with the `context' will
+ * be called after the key agreement protocol.
+ *
+ * NOTES
+ *
+ * NOTE: If the application returns TRUE in the `key_agreement' client
+ * operation the library will automatically start the key agreement. In this
+ * case the application must not call this function. However, application
+ * may choose to just ignore the `key_agreement' client operation (and
+ * merely just print information about it on the screen) and call this
+ * function when the user whishes to do so (by, for example, giving some
+ * specific command). Thus, the API provides both, automatic and manual
+ * initiation of the key agreement. Calling this function is the manual
+ * initiation and returning TRUE in the `key_agreement' client operation
+ * is the automatic initiation.
+ *
+ ***/
+void silc_client_perform_key_agreement(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ char *hostname,
+ int port,
+ SilcKeyAgreementCallback completion,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_perform_key_agreement_fd
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_client_perform_key_agreement_fd(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry,
+ * int sock,
+ * char *hostname,
+ * SilcKeyAgreementCallback completion,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Same as above but application has created already the connection to
+ * the remote host. The `sock' is the socket to the remote connection.
+ * Application can use this function if it does not want the client library
+ * to create the connection.
+ *
+ ***/
+void silc_client_perform_key_agreement_fd(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry,
+ int sock,
+ char *hostname,
+ SilcKeyAgreementCallback completion,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_abort_key_agreement
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_abort_key_agreement(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcClientEntry client_entry);
+ *
+ * DESCRIPTION
+ *
+ * This function can be called to unbind the hostname and the port for
+ * the key agreement protocol. However, this function has effect only
+ * before the key agreement protocol has been performed. After it has
+ * been performed the library will automatically unbind the port. The
+ * `client_entry' is the client to which we sent the key agreement
+ * request.
+ *
+ ***/
+void silc_client_abort_key_agreement(SilcClient client,
+ SilcClientConnection conn,
+ SilcClientEntry client_entry);
+
+
+/* Misc functions */
+
+/****f* silcclient/SilcClientAPI/silc_client_set_away_message
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_set_away_message(SilcClient client,
+ * SilcClientConnection conn,
+ * char *message);
+ *
+ * DESCRIPTION
+ *
+ * Sets away `message'. The away message may be set when the client's
+ * mode is changed to SILC_UMODE_GONE and the client whishes to reply
+ * to anyone who sends private message. The `message' will be sent
+ * automatically back to the the client who send private message. If
+ * away message is already set this replaces the old message with the
+ * new one. If `message' is NULL the old away message is removed.
+ * The sender may freely free the memory of the `message'.
+ *
+ ***/
+void silc_client_set_away_message(SilcClient client,
+ SilcClientConnection conn,
+ char *message);
+
+
+/****f* silcclient/SilcClientAPI/SilcConnectionAuthRequest
+ *
+ * SYNOPSIS
+ *
+ * typedef void (*SilcConnectionAuthRequest)(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcAuthMethod auth_meth,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * Connection authentication method request callback. This is called
+ * by the client library after it has received the authentication method
+ * that the application requested by calling the function
+ * silc_client_request_authentication_method.
+ *
+ ***/
+typedef void (*SilcConnectionAuthRequest)(SilcClient client,
+ SilcClientConnection conn,
+ SilcAuthMethod auth_meth,
+ void *context);
+
+/****f* silcclient/SilcClientAPI/silc_client_request_authentication_method
+ *
+ * SYNOPSIS
+ *
+ * void
+ * silc_client_request_authentication_method(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcConnectionAuthRequest
+ * callback,
+ * void *context);
+ *
+ * DESCRIPTION
+ *
+ * This function can be used to request the current authentication method
+ * from the server. This may be called when connecting to the server
+ * and the client library requests the authentication data from the
+ * application. If the application does not know the current authentication
+ * method it can request it from the server using this function.
+ * The `callback' with `context' will be called after the server has
+ * replied back with the current authentication method.
+ *
+ ***/
+void
+silc_client_request_authentication_method(SilcClient client,
+ SilcClientConnection conn,
+ SilcConnectionAuthRequest callback,
+ void *context);