extern "C" {
#endif
-/* Forward declarations */
-typedef struct SilcClientStruct *SilcClient;
-typedef struct SilcClientConnectionStruct *SilcClientConnection;
-typedef struct SilcClientPingStruct SilcClientPing;
-typedef struct SilcClientAwayStruct SilcClientAway;
-typedef struct SilcClientKeyAgreementStruct *SilcClientKeyAgreement;
-typedef struct SilcClientFtpSessionStruct *SilcClientFtpSession;
-typedef struct SilcClientEntryStruct *SilcClientEntry;
-typedef struct SilcChannelEntryStruct *SilcChannelEntry;
-typedef struct SilcServerEntryStruct *SilcServerEntry;
-typedef struct SilcClientCommandStruct *SilcClientCommand;
-typedef struct SilcClientCommandContextStruct *SilcClientCommandContext;
-typedef struct SilcClientCommandReplyContextStruct
- *SilcClientCommandReplyContext;
-typedef struct SilcChannelUserStruct *SilcChannelUser;
+#include "client.h"
/* General definitions */
+/****s* silcclient/SilcClientAPI/SilcClient
+ *
+ * NAME
+ *
+ * typedef struct SilcClientStruct { ... } *SilcClient
+ *
+ * DESCRIPTION
+ *
+ * This is the actual SILC Client structure which represents one
+ * SILC Client. It is allocated with the silc_client_alloc function
+ * and given as argument to all SILC Client Library functions. It
+ * is initialized with silc_client_init function, and freed with
+ * silc_client_free function.
+ *
+ * SOURCE
+ */
+struct SilcClientStruct {
+ /*
+ * The following fields are set by application
+ */
+ char *nickname; /* Nickname, MAY be set by application */
+ char *username; /* Username, MUST be set by application */
+ char *hostname; /* hostname, MUST be set by application */
+ char *realname; /* Real name, MUST be set be application */
+
+ SilcPublicKey public_key; /* Public key of user, set by application */
+ SilcPrivateKey private_key; /* Private key of user, set by application */
+ SilcPKCS pkcs; /* PKCS allocated by application */
+
+ /*
+ * The following fields are set by the library
+ */
+
+ /* Scheduler, set by library. Application may use this pointer. */
+ SilcSchedule schedule;
+
+ /* Random Number Generator. Application should use this as its primary
+ random number generator. */
+ SilcRng rng;
+
+ /* Application specific user data pointer. Client library does not
+ touch this. This the context sent as argument to silc_client_alloc.
+ Application can use it freely. */
+ void *application;
+
+ /* Generic hash context for application usage */
+ SilcHash md5hash;
+ SilcHash sha1hash;
+
+ /* Internal data for client library. Application cannot access this
+ data at all. */
+ SilcClientInternal internal;
+};
+/***/
+
+/****s* silcclient/SilcClientAPI/SilcClientConnection
+ *
+ * NAME
+ *
+ * typedef struct SilcClientConnectionStruct { ... }
+ * *SilcClientConnection
+ *
+ * DESCRIPTION
+ *
+ * This structure represents a connection. When connection is created
+ * to server this is context is returned to the application in the
+ * "connected" client operation. It includes all the important
+ * data for the session, such as nickname, local and remote IDs, and
+ * other information.
+ *
+ * SOURCE
+ */
+struct SilcClientConnectionStruct {
+ /*
+ * Local data
+ */
+ char *nickname; /* Current nickname */
+ SilcClientEntry local_entry; /* Own Client Entry */
+ SilcClientID *local_id; /* Current Client ID */
+ unsigned char *local_id_data; /* Current Client ID decoded */
+ SilcUInt32 local_id_data_len;
+
+ /*
+ * Remote data
+ */
+ char *remote_host; /* Remote host name */
+ int remote_port; /* Remote port */
+ SilcServerID *remote_id; /* Remote Server ID */
+ unsigned char *remote_id_data; /* Remote Server ID decoded */
+ SilcUInt32 remote_id_data_len;
+
+ /*
+ * Common data
+ */
+
+ /* User data context. Library does not touch this. Application may
+ freely set and use this pointer for its needs. */
+ void *context;
+
+ /* Pointer back to the SilcClient. Application may use this. */
+ SilcClient client;
+
+ /* Current channel. Application may use and set this pointer if needed. */
+ SilcChannelEntry current_channel;
+
+ /* Socket connection object for this connection. Application may
+ use this if needed. The sock->user_data is back pointer to this
+ structure. */
+ SilcSocketConnection sock;
+
+ /* Current command identifier, 0 not used */
+ SilcUInt16 cmd_ident;
+
+ /* Internal data for client library. Application cannot access this
+ data at all. */
+ SilcClientConnectionInternal internal;
+};
+/***/
+
/****d* silcclient/SilcClientAPI/SilcKeyAgreementStatus
*
* NAME
/* Message sent to the application by library. `conn' associates the
message to a specific connection. `conn', however, may be NULL.
The `type' indicates the type of the message sent by the library.
- The applicationi can for example filter the message according the
+ The application can for example filter the message according the
type. */
void (*say)(SilcClient client, SilcClientConnection conn,
SilcClientMessageType type, char *msg, ...);
/* Message for a channel. The `sender' is the sender of the message
- The `channel' is the channel. The `msg' is the message. Note that
- `msg' maybe NULL. */
+ The `channel' is the channel. The `message' is the message. Note
+ that `message' maybe NULL. The `flags' indicates message flags
+ and it is used to determine how the message can be interpreted
+ (like it may tell the message is multimedia message). */
void (*channel_message)(SilcClient client, SilcClientConnection conn,
SilcClientEntry sender, SilcChannelEntry channel,
SilcMessageFlags flags,
SilcUInt32 message_len);
/* Private message to the client. The `sender' is the sender of the
- message. */
+ message. The message is `message'and maybe NULL. The `flags'
+ indicates message flags and it is used to determine how the message
+ can be interpreted (like it may tell the message is multimedia
+ message). */
void (*private_message)(SilcClient client, SilcClientConnection conn,
SilcClientEntry sender, SilcMessageFlags flags,
const unsigned char *message,
The `status' indicated whether the connection were successful. If it
is error value the application must always call the function
silc_client_close_connection. */
- void (*connect)(SilcClient client, SilcClientConnection conn,
- SilcClientConnectionStatus status);
+ void (*connected)(SilcClient client, SilcClientConnection conn,
+ SilcClientConnectionStatus status);
/* Called to indicate that connection was disconnected to the server.
The `status' may tell the reason of the disconnection, and if the
`message' is non-NULL it may include the disconnection message
received from server. */
- void (*disconnect)(SilcClient client, SilcClientConnection conn,
- SilcStatus status, const char *message);
+ void (*disconnected)(SilcClient client, SilcClientConnection conn,
+ SilcStatus status, const char *message);
/* Find authentication method and authentication data by hostname and
port. The hostname may be IP address as well. When the authentication
/* Verifies received public key. The `conn_type' indicates which entity
(server, client etc.) has sent the public key. If user decides to trust
- the key may be saved as trusted public key for later use. The
- `completion' must be called after the public key has been verified. */
+ the application may save the key as trusted public key for later
+ use. The `completion' must be called after the public key has been
+ verified. */
void (*verify_public_key)(SilcClient client, SilcClientConnection conn,
SilcSocketType conn_type, unsigned char *pk,
SilcUInt32 pk_len, SilcSKEPKType pk_type,
desired (application may start it later by calling the function
silc_client_perform_key_agreement). If TRUE is returned also the
`completion' and `context' arguments must be set by the application. */
- int (*key_agreement)(SilcClient client, SilcClientConnection conn,
- SilcClientEntry client_entry, const char *hostname,
- SilcUInt16 port, SilcKeyAgreementCallback *completion,
- void **context);
+ bool (*key_agreement)(SilcClient client, SilcClientConnection conn,
+ SilcClientEntry client_entry, const char *hostname,
+ SilcUInt16 port, SilcKeyAgreementCallback *completion,
+ void **context);
/* Notifies application that file transfer protocol session is being
requested by the remote client indicated by the `client_entry' from
nickname string whenever it needs the true nickname. */
SilcNicknameFormatParse nickname_parse;
+ /* If this is set to TRUE then the client will ignore all incoming
+ Requested Attributes queries and does not reply anything back. This
+ usually leads into situation where server does not anymore send
+ the queries after seeing that client does not reply anything back.
+ If your application does not support Requested Attributes or you do
+ not want to use them set this to TRUE. See SilcAttribute and
+ silc_client_attribute_add for more information on attributes. */
+ bool ignore_requested_attributes;
+
} SilcClientParams;
/***/
SilcClient silc_client_alloc(SilcClientOperations *ops,
SilcClientParams *params,
void *application,
- const char *silc_version);
+ const char *version_string);
/****f* silcclient/SilcClientAPI/silc_client_free
*
*
* Runs the client. This starts the scheduler from the utility library.
* When this functions returns the execution of the appliation is over.
+ * The client must be initialized before calling this.
*
***/
void silc_client_run(SilcClient client);
* silc_client_get_client_by_id_resolve(SilcClient client,
* SilcClientConnection conn,
* SilcClientID *client_id,
+ * SilcBuffer attributes,
* SilcGetClientCallback completion,
* void *context);
*
* is its ID. When server returns the client information it will be
* cache and can be accessed locally at a later time.
*
+ * If the `attributes' is non-NULL then the buffer includes Requested
+ * Attributes which can be used to fetch very detailed information
+ * about the user. If it is NULL then only normal WHOIS query is
+ * made (for more information about attributes see SilcAttribute).
+ * Caller may create the `attributes' with silc_client_attributes_request
+ * function.
+ *
***/
void silc_client_get_client_by_id_resolve(SilcClient client,
SilcClientConnection conn,
SilcClientID *client_id,
+ SilcBuffer attributes,
SilcGetClientCallback completion,
void *context);
* directly to the server using this function. If application is using
* the silc_client_command_call, this function is usually not used.
*
+ * The variable arguments are a pair of { type, data, data_length },
+ * and the `argc' is the number of these pairs.
+ *
+ * EXAMPLE
+ *
+ * silc_client_command_send(client, conn, SILC_COMMAND_WHOIS, 0, 1,
+ * 1, nickname, strlen(nickname));
+ *
***/
void silc_client_command_send(SilcClient client, SilcClientConnection conn,
SilcCommand command, SilcUInt16 ident,
SilcSKEKeyMaterial *key,
bool responder);
-/****f* silcclient/SilcClientAPI/silc_client_send_private_message_key
- *
- * SYNOPSIS
- *
- * int silc_client_send_private_message_key(SilcClient client,
- * SilcClientConnection conn,
- * SilcClientEntry client_entry,
- * int force_send);
- *
- * DESCRIPTION
- *
- * Sends private message key payload to the remote client indicated by
- * the `client_entry'. If the `force_send' is TRUE the packet is sent
- * immediately. Returns FALSE if error occurs, TRUE otherwise. The
- * application should call this function after setting the key to the
- * client.
- *
- * Note that the key sent using this function is sent to the remote client
- * through the SILC network. The packet is protected using normal session
- * keys.
- *
- ***/
-int silc_client_send_private_message_key(SilcClient client,
- SilcClientConnection conn,
- SilcClientEntry client_entry,
- int force_send);
-
/****f* silcclient/SilcClientAPI/silc_client_del_private_message_key
*
* SYNOPSIS
SilcClientConnection conn,
char *message);
-
/****f* silcclient/SilcClientAPI/SilcConnectionAuthRequest
*
* SYNOPSIS
SilcClientConnection conn,
SilcUInt32 session_id);
-#include "client.h"
+/****f* silcclient/SilcClientAPI/silc_client_attribute_add
+ *
+ * SYNOPSIS
+ *
+ * SilcAttributePayload
+ * silc_client_attribute_add(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcAttribute attribute,
+ * void *object,
+ * SilcUInt32 object_size);
+ *
+ * DESCRIPTION
+ *
+ * Add new Requsted Attribute for WHOIS command to the client library.
+ * The `attribute' object indicated by `object' is added and allocated
+ * SilcAttributePayload is returned. The `object' must be of correct
+ * type and of correct size. See the SilcAttribute for object types
+ * for different attributes. You may also get all added attributes
+ * from the client with silc_client_attributes_get function.
+ *
+ * Requested Attributes are different personal information about the
+ * user, status information and other information which other users
+ * may query with WHOIS command. Application may set these so that
+ * if someone sends WHOIS query these attributes will be replied back
+ * to the sender. The library always puts the public key to the
+ * Requested Attributes, but if application wishes to add additional
+ * public keys (or certificates) it can be done with this interface.
+ * Library also always computes digital signature of the attributes
+ * automatically, so application does not need to do that.
+ *
+ ***/
+SilcAttributePayload silc_client_attribute_add(SilcClient client,
+ SilcClientConnection conn,
+ SilcAttribute attribute,
+ void *object,
+ SilcUInt32 object_size);
+
+/****f* silcclient/SilcClientAPI/silc_client_attribute_del
+ *
+ * SYNOPSIS
+ *
+ * bool silc_client_attribute_del(SilcClient client,
+ * SilcClientConnection conn,
+ * SilcAttribute attribute,
+ * SilcAttributePayload attr);
+ *
+ * DESCRIPTION
+ *
+ * Delete a Requested Attribute from the client. If the `attribute'
+ * is non-zero then all attributes of that type are deleted and the
+ * `attr' is ignored. If `attr' is non-NULL then that specific
+ * attribute is deleted and `attribute' is ignored.
+ *
+ * You may get all added attributes with the function
+ * silc_client_attributes_get and to get the SilcAttributePayload.
+ * This function Returns TRUE if the attribute was found and deleted.
+ *
+ ***/
+bool silc_client_attribute_del(SilcClient client,
+ SilcClientConnection conn,
+ SilcAttribute attribute,
+ SilcAttributePayload attr);
+
+/****f* silcclient/SilcClientAPI/silc_client_attributes_get
+ *
+ * SYNOPSIS
+ *
+ * const SilcHashTable
+ * silc_client_attributes_get(SilcClient client,
+ * SilcClientConnection conn);
+ *
+ * DESCRIPTION
+ *
+ * Returns pointer to the SilcHashTable which includes all the added
+ * Requested Attributes. The caller must not free the hash table.
+ * The caller may use SilcHashTableList and silc_hash_table_list to
+ * traverse the table. Each entry in the hash table is one added
+ * SilcAttributePayload. It is possible to delete a attribute
+ * payload while traversing the table.
+ *
+ ***/
+const SilcHashTable silc_client_attributes_get(SilcClient client,
+ SilcClientConnection conn);
+
+/****f* silcclient/SilcClientAPI/silc_client_attributes_request
+ *
+ * SYNOPSIS
+ *
+ * SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
+ *
+ * DESCRIPTION
+ *
+ * Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
+ * then all attributes are requested. Alternatively, `attribute' and
+ * all variable arguments can each be requested attribute. In this case
+ * the last must be set to zero (0) to complete the variable list of
+ * requested attributes. See SilcAttribute for all attributes.
+ * You can give the returned buffer as argument to for example
+ * silc_client_get_client_by_id_resolve function.
+ *
+ ***/
+SilcBuffer silc_client_attributes_request(SilcAttribute attribute, ...);
+
+/* Low level packet sending functions */
+
+/****f* silcclient/SilcClientAPI/silc_client_packet_send
+ *
+ * SYNOPSIS
+ *
+ * void silc_client_packet_send(SilcClient client,
+ * SilcSocketConnection sock,
+ * SilcPacketType type,
+ * void *dst_id,
+ * SilcIdType dst_id_type,
+ * SilcCipher cipher,
+ * SilcHmac hmac,
+ * unsigned char *data,
+ * SilcUInt32 data_len,
+ * bool force_send);
+ *
+ * DESCRIPTION
+ *
+ * Constructs a Requested Attributes buffer. If the `attribute' is zero (0)
+ * then all attributes are requested. Alternatively, `attribute' and
+ * all variable arguments can each be requested attribute. In this case
+ * the last must be set to zero (0) to complete the variable list of
+ * requested attributes. See SilcAttribute for all attributes.
+ * You can give the returned buffer as argument to for example
+ * silc_client_get_client_by_id_resolve function.
+ *
+ ***/
+void silc_client_packet_send(SilcClient client,
+ SilcSocketConnection sock,
+ SilcPacketType type,
+ void *dst_id,
+ SilcIdType dst_id_type,
+ SilcCipher cipher,
+ SilcHmac hmac,
+ unsigned char *data,
+ SilcUInt32 data_len,
+ bool force_send);
+
#include "command.h"
#include "command_reply.h"
#include "idlist.h"