Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2005 Pekka Riikonen
+ Copyright (C) 1997 - 2006 Pekka Riikonen
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
*
* DESCRIPTION
*
- * Implementation of the packet routines for sending and receiving
- * SILC Packets. These includes the data sending routines and data
- * reading routines, encrypting and decrypting routines, packet assembling
- * and packet parsing routines.
+ * The SILC secure binary packet protocol interface, provides interface for
+ * sending and receiving SILC packets. The interface provides a packet
+ * engine, that can be used to receive packets from packet streams, and
+ * routines for sending all kinds of SILC packets.
+ *
+ * The packet engine and packet stream are thread safe. They can be safely
+ * used in multi threaded environment.
*
***/
typedef SilcUInt8 SilcPacketType;
/* SILC Packet types. */
-#define SILC_PACKET_NONE 0 /* NULL, never sent */
#define SILC_PACKET_DISCONNECT 1 /* Disconnection */
#define SILC_PACKET_SUCCESS 2 /* Success */
#define SILC_PACKET_FAILURE 3 /* Failure */
#define SILC_PACKET_PRIVATE 200 /* Private range start */
#define SILC_PACKET_MAX 255 /* RESERVED */
+
+#define SILC_PACKET_NONE 0 /* RESERVED */
+#define SILC_PACKET_ANY 0
/***/
/****d* silccore/SilcPacketAPI/SilcPacketFlags
* callback. The application can parse the data payload from the
* SilcPacket. Also packet type, flags, and sender and destination
* IDs are available. The application must free the packet with the
- * silc_packet_free function.
+ * silc_packet_free function if it takes it in for processing.
+ *
+ * The list pointer `next' can be used by the application to put the
+ * packet context in a list during processing, if needed.
*
* SOURCE
*/
typedef struct SilcPacketStruct {
- struct SilcPacketStruct *next;
- SilcBufferStruct buffer; /* Packet data payload */
- unsigned char *src_id; /* Source ID */
- unsigned char *dst_id; /* Destination ID */
- unsigned int src_id_len : 6; /* Source ID length */
- unsigned int src_id_type : 2; /* Source ID type */
- unsigned int dst_id_len : 6; /* Destination ID length */
- unsigned int dst_id_type : 2; /* Destination ID type */
- SilcPacketType type; /* Packet type */
- SilcPacketFlags flags; /* Packet flags */
+ struct SilcPacketStruct *next; /* List pointer, application may set */
+ SilcPacketStream stream; /* Packet stream this packet is from */
+ SilcBufferStruct buffer; /* Packet data payload */
+ unsigned char *src_id; /* Source ID */
+ unsigned char *dst_id; /* Destination ID */
+ unsigned int src_id_len : 6; /* Source ID length */
+ unsigned int src_id_type : 2; /* Source ID type */
+ unsigned int dst_id_len : 6; /* Destination ID length */
+ unsigned int dst_id_type : 2; /* Destination ID type */
+ SilcPacketType type; /* Packet type */
+ SilcPacketFlags flags; /* Packet flags */
} *SilcPacket;
/***/
*
* Packet errors. This is returned in the error callback. If application
* needs the actual lower level stream error, it needs to retrieve it
- * from the actual stream.
+ * from the actual stream. It can retrieve the underlaying stream from
+ * the packet stream by calling silc_packet_stream_get_stream function.
*
* SOURCE
*/
SILC_PACKET_ERR_WRITE, /* Error while writing */
SILC_PACKET_ERR_MAC_FAILED, /* Packet MAC check failed */
SILC_PACKET_ERR_DECRYPTION_FAILED, /* Packet decryption failed */
+ SILC_PACKET_ERR_UNKNOWN_SID, /* Unknown SID (with IV included) */
SILC_PACKET_ERR_MALFORMED, /* Packet is malformed */
SILC_PACKET_ERR_NO_MEMORY, /* System out of memory */
} SilcPacketError;
*
* SYNOPSIS
*
- * typedef void (*SilcPacketReceiveCb)(SilcPacketEngine engine,
- * SilcPacketStream stream,
- * SilcPacket packet,
- * void *callback_context,
- * void *app_context);
+ * typedef SilcBool (*SilcPacketReceiveCb)(SilcPacketEngine engine,
+ * SilcPacketStream stream,
+ * SilcPacket packet,
+ * void *callback_context,
+ * void *stream_context);
*
* DESCRIPTION
*
* The packet receive callback is called by the packet engine when a new
* SILC Packet has arrived. The application must free the returned
- * SilcPacket with silc_packet_free. This callback is set in the
- * SilcPacketCallbacks structure.
+ * SilcPacket with silc_packet_free if it takes the packet in for
+ * processing. This callback is set in the SilcPacketCallbacks structure.
+ * The `callback_context' is the context set as argument in the
+ * silc_packet_engine_start function. The `stream_context' is stream
+ * specific context that was set by calling silc_packet_set_context.
+ *
+ * If the application takes the received packet `packet' into processing
+ * TRUE must be returned. If FALSE is returned the packet engine will
+ * pass the packet to other packet processor, if one has been linked
+ * to the stream with silc_packet_stream_link function. If no extra
+ * processor is linked the packet is dropped.
+ *
+ * EXAMPLE
+ *
+ * SilcBool
+ * silc_foo_packet_receive_cb(SilcPacketEngine engine,
+ * SilcPacketStream stream, SilcPacket packet,
+ * void *callback_context, void *stream_context)
+ * {
+ * Application ctx = callback_context;
+ *
+ * // If we're not up yet, let's not process the packet
+ * if (ctx->initialized == FALSE)
+ * return FALSE;
+ *
+ * // Process the incoming packet...
+ * ...
+ *
+ * // It's our packet now, no one else will get it
+ * return TRUE;
+ * }
*
***/
-typedef void (*SilcPacketReceiveCb)(SilcPacketEngine engine,
- SilcPacketStream stream,
- SilcPacket packet,
- void *callback_context,
- void *app_context);
+typedef SilcBool (*SilcPacketReceiveCb)(SilcPacketEngine engine,
+ SilcPacketStream stream,
+ SilcPacket packet,
+ void *callback_context,
+ void *stream_context);
/****f* silccore/SilcPacketAPI/SilcPacketEosCb
*
* typedef void (*SilcPacketEosCb)(SilcPacketEngine engine,
* SilcPacketStream stream,
* void *callback_context,
- * void *app_context);
+ * void *stream_context);
*
* DESCRIPTION
*
typedef void (*SilcPacketEosCb)(SilcPacketEngine engine,
SilcPacketStream stream,
void *callback_context,
- void *app_context);
+ void *stream_context);
/****f* silccore/SilcPacketAPI/SilcPacketErrorCb
*
* SilcPacketStream stream,
* SilcPacketError error,
* void *callback_context,
- * void *app_context);
+ * void *stream_context);
*
* DESCRIPTION
*
SilcPacketStream stream,
SilcPacketError error,
void *callback_context,
- void *app_context);
+ void *stream_context);
/****s* silccore/SilcPacketAPI/SilcPacketStream
*
* SYNOPSIS
*
* SilcPacketEngine
- * silc_packet_engine_start(SilcSchedule schedule, SilcRng rng, bool router,
+ * silc_packet_engine_start(SilcRng rng, SilcBool router,
* SilcPacketCallbacks *callbacks,
* void *callback_context);
*
* DESCRIPTION
*
* Create new packet engine for processing incoming and outgoing packets.
- * If `rng' is non-NULL that RNG will be used to create necessary random
- * numbers during packet processing. If NULL, Global RNG will be used.
* If `router' is TRUE then the application is considered to be router
* server, and certain packets are handled differently. Client and normal
* server must set it to FALSE. The `callbacks' is a SilcPacketCallbacks
* structure provided by the caller which includes the callbacks that is
- * called when for example packet is received, or end of stream is called
+ * called when for example packet is received, or end of stream is called.
*
* NOTES
*
- * The packet engine is thread safe. Also the `schedule' and `rng' are
- * thread safe. You can use one packet engine in multi threaded
- * application.
+ * The packet engine is thread safe. You can use one packet engine in
+ * multi threaded application.
*
***/
SilcPacketEngine
-silc_packet_engine_start(SilcSchedule schedule, SilcRng rng, bool router,
+silc_packet_engine_start(SilcRng rng, SilcBool router,
SilcPacketCallbacks *callbacks,
void *callback_context);
* SYNOPSIS
*
* SilcPacketStream silc_packet_stream_create(SilcPacketEngine engine,
+ * SilcSchedule schedule,
* SilcStream stream);
*
* DESCRIPTION
* To read packets you will receive the packet receive callback from
* packet engine. Destroy the stream with silc_packet_stream_destroy.
*
- * If you need to send only one type of SILC packets, then it is possible
- * to create SILC Packet Streamer with silc_packet_streamer_create, which
- * can be used with silc_stream_read and silc_stream_write.
- *
- * The SilcPacketStream is not thread safe. If you share same stream
- * with multiple threads concurrency control need to be employed. It
- * is recommended to create new SilcPacketStream for every thread.
+ * The SilcPacketStream is thread safe. Same context can be safely used
+ * in multi threaded environment.
*
***/
SilcPacketStream silc_packet_stream_create(SilcPacketEngine engine,
+ SilcSchedule schedule,
SilcStream stream);
/****f* silccore/SilcPacketAPI/silc_packet_stream_destroy
***/
void silc_packet_stream_destroy(SilcPacketStream stream);
-/****f* silccore/SilcPacketAPI/silc_packet_streamer_create
+/****f* silccore/SilcPacketAPI/silc_packet_stream_set_router
*
* SYNOPSIS
*
- * SilcStream silc_packet_streamer_create(SilcPacketStream stream,
- * SilcPacketType packet_type,
- * SilcPacketFlags packet_flags);
+ * void silc_packet_stream_set_router(SilcPacketStream stream);
*
* DESCRIPTION
*
- * This function can be used to create a SILC Packet Streamer that will
- * stream only one type of packet indicated by `packet_type' with packet
- * flags `packet_flags'. This is special purpose function as usually
- * multiple different types of packets need to be sent in application.
- * There are cases however when creating streamer is simpler and more
- * efficient. Cases such as file transfer stream or other data streams
- * that only send and receive one type of packet. While it would be
- * possible to use silc_packet_send function to send packets it is
- * more efficient to create the SILC Packet Streamer and use the
- * silc_stream_read and silc_stream_write functions.
- *
- * The encryption and decryption keys, and other information will be
- * retrieved from the packet stream indicated by `stream', which must be
- * created before creating the streamer.
- *
- * NOTES
- *
- * The packet type that is assocated with the packet stream `stream' will
- * only be available through the returned SilcStream. That packet type
- * will not be delivered to the packet callbacks. To return to the
- * normal operation destroy the streamer silc_packet_streamer_destroy.
+ * When called sets the stream indicates by `stream' as SILC router
+ * connection stream. This causes that certain packets are handled
+ * differently. This must be called for router connection streams and
+ * must not be called for any other stream.
*
***/
-SilcStream silc_packet_streamer_create(SilcPacketStream stream,
- SilcPacketType packet_type,
- SilcPacketFlags packet_flags);
+void silc_packet_stream_set_router(SilcPacketStream stream);
-/****f* silccore/SilcPacketAPI/silc_packet_streamer_destroy
+/****f* silccore/SilcPacketAPI/silc_packet_stream_set_iv_included
*
* SYNOPSIS
*
- * void silc_packet_streamer_destroy(SilcStream stream);
+ * void silc_packet_stream_set_iv_included(SilcPacketStream stream);
*
* DESCRIPTION
*
- * Destroys the created packet streamer. Use this function only for
- * stream created with silc_packet_streamer_create. The packet type
- * that was associated with the streamer can be received in the packet
- * callbacks after the streamer is destroyed.
+ * Sets an IV Included property for the stream indicated by `stream'.
+ * This means that the IV used in the encryption will be included in
+ * the resulted ciphertext. This makes it possible to send and receive
+ * packets on unreliable network transport protocol, such as UDP/IP.
+ * This must be called if the underlaying stream in the `stream' is UDP
+ * stream.
+ *
+ * When this is set to the stream the silc_packet_set_sid must be called
+ * to set new Security ID. The Security ID will be included with the IV
+ * in the ciphertext.
*
***/
-void silc_packet_streamer_destroy(SilcStream stream);
+void silc_packet_stream_set_iv_included(SilcPacketStream stream);
/****f* silccore/SilcPacketAPI/silc_packet_stream_get_stream
*
* Returns the actual stream that is associated with the packet stream
* `stream'. The caller must not free the returned stream. The returned
* stream is the same pointer that was set for silc_packet_stream_create.
- * This function couled be used for example when an error callback is
+ * This function could be used for example when an error callback is
* called by the packet engine to retrieve the actual lower level error
* from the stream.
*
***/
SilcStream silc_packet_stream_get_stream(SilcPacketStream stream);
-/****f* silccore/SilcPacketAPI/silc_packet_stream_callbacks
+/****f* silccore/SilcPacketAPI/silc_packet_stream_link
*
* SYNOPSIS
*
- * void silc_packet_stream_callbacks(SilcPacketStream stream,
- * SilcPacketCallbacks *callbacks,
- * void *callback_context);
+ * SilcBool silc_packet_stream_link(SilcPacketStream stream,
+ * SilcPacketCallbacks *callbacks,
+ * void *callback_context,
+ * int priority, ...);
*
* DESCRIPTION
*
- * This is optional function which can be used to set specific callbacks
- * for the packet stream indicated by `stream'. If these are set then
- * `callbacks' will be used instead of the ones set for the function
- * silc_packet_engine_start. To reset the normal behaviour call this
- * function again with `callbacks' as NULL. Note that the responsibility
- * of handling end of stream, and error conditions moves to the layer
- * calling this function since the original callbacks set in the
- * silc_packet_engine_start will not be called.
+ * Links the packet processing callbacks indicated by `callbacks' into
+ * the packet stream indicated by `stream' with priority `priority' for
+ * the packet types given in the variable argument list. This function
+ * can be used to link to the packet stream for specific packet types
+ * and receive them in the specified callbacks. This way, a third party,
+ * for example some library may attach itself into the packet stream
+ * and receive and process certain packets. The variable argument
+ * list is ended with -1. To link to receive all packets use
+ * SILC_PACKET_ANY.
+ *
+ * The default packet processing callbacks given as argument to the
+ * silc_packet_engine_start has the priority 0. Any priority higher
+ * than 0 will then take precedence over the default callbacks. Any
+ * priority lower than 0 (negative value) will be processed after the
+ * default callbacks.
+ *
+ * Note that setting only the 'packet_receive' callback in the `callbacks'
+ * is required.
+ *
+ * EXAMPLE
+ *
+ * // Link to this packet stream, with high priority, for
+ * // SILC_PACKET_CONNECTION_AUTH and SILC_PACKET_CONNECTION_AUTH_REQUEST
+ * // packets. We don't care about other packets.
+ * silc_packet_stream_link(stream, our_callbacks, our_context,
+ * 1000000, SILC_PACKET_CONNECTION_AUTH,
+ * SILC_PACKET_CONNECTION_AUTH_REQUEST, -1);
*
***/
-void silc_packet_stream_callbacks(SilcPacketStream stream,
- SilcPacketCallbacks *callbacks,
- void *callback_context);
+SilcBool silc_packet_stream_link(SilcPacketStream stream,
+ SilcPacketCallbacks *callbacks,
+ void *callback_context,
+ int priority, ...);
+
+/****f* silccore/SilcPacketAPI/silc_packet_stream_unlink
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_stream_unlink(SilcPacketStream stream,
+ * SilcPacketCallbacks *callbacks,
+ * void *callback_context);
+ *
+ * DESCRIPTION
+ *
+ * Unlinks the `callbacks' with `callback_context' from the packet stream
+ * indicated by `stream'. This function must be called for the callbacks
+ * that was linked to `stream' when they are not needed anymore.
+ *
+ ***/
+void silc_packet_stream_unlink(SilcPacketStream stream,
+ SilcPacketCallbacks *callbacks,
+ void *callback_context);
/****f* silccore/SilcPacketAPI/silc_packet_stream_ref
*
***/
void silc_packet_stream_unref(SilcPacketStream stream);
+/****f* silccore/SilcPacketAPI/silc_packet_get_engine
+ *
+ * SYNOPSIS
+ *
+ * SilcPacketEngine silc_packet_get_engine(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Returns the packet engine from the `stream'.
+ *
+ ***/
+SilcPacketEngine silc_packet_get_engine(SilcPacketStream stream);
+
/****f* silccore/SilcPacketAPI/silc_packet_set_context
*
* SYNOPSIS
*
- * void silc_packet_set_context(SilcPacketStream stream, void *app_context);
+ * void silc_packet_set_context(SilcPacketStream stream,
+ * void *stream_context);
*
* DESCRIPTION
*
- * Set an application specific context to the stream. The context will
+ * Sets a stream specific context to the stream. The context will
* be delivered to all callback functions, and it can be retrieved by
* calling silc_packet_get_context function as well. Note that this is
* separate packet stream specific context, and not the same as
* `callback_context' in silc_packet_engine_start. Both will be delivered
- * to the callbacks.
+ * to the callbacks, and this context as the `stream_context' argument.
*
***/
-void silc_packet_set_context(SilcPacketStream stream, void *app_context);
+void silc_packet_set_context(SilcPacketStream stream, void *stream_context);
/****f* silccore/SilcPacketAPI/silc_packet_get_context
*
*
* SYNOPSIS
*
- * bool silc_packet_get_ciphers(SilcPacketStream stream, SilcCipher *send,
- * SilcCipher *receive);
+ * SilcBool silc_packet_get_ciphers(SilcPacketStream stream,
+ * SilcCipher *send,
+ * SilcCipher *receive);
*
* DESCRIPTION
*
* FALSE if ciphers are not set.
*
***/
-bool silc_packet_get_ciphers(SilcPacketStream stream, SilcCipher *send,
- SilcCipher *receive);
+SilcBool silc_packet_get_ciphers(SilcPacketStream stream, SilcCipher *send,
+ SilcCipher *receive);
/****f* silccore/SilcPacketAPI/silc_packet_set_hmacs
*
*
* SYNOPSIS
*
- * bool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
- * SilcHmac *receive);
+ * SilcBool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
+ * SilcHmac *receive);
*
* DESCRIPTION
*
* FALSE if HMACs are not set.
*
***/
-bool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
- SilcHmac *receive);
+SilcBool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
+ SilcHmac *receive);
/****f* silccore/SilcPacketAPI/silc_packet_set_ids
*
* SYNOPSIS
*
- * bool silc_packet_set_ids(SilcPacketStream stream,
- * SilcIdType src_id_type, const void *src_id
- * SilcIdType dst_id_type, const void *dst_id);
+ * SilcBool silc_packet_set_ids(SilcPacketStream stream,
+ * SilcIdType src_id_type, const void *src_id
+ * SilcIdType dst_id_type, const void *dst_id);
*
* DESCRIPTION
*
* It is also possible to set only source or destination ID.
*
***/
-bool silc_packet_set_ids(SilcPacketStream stream,
- SilcIdType src_id_type, const void *src_id,
- SilcIdType dst_id_type, const void *dst_id);
+SilcBool silc_packet_set_ids(SilcPacketStream stream,
+ SilcIdType src_id_type, const void *src_id,
+ SilcIdType dst_id_type, const void *dst_id);
+
+/****f* silccore/SilcPacketAPI/silc_packet_set_sid
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_set_sid(SilcPacketStream stream, SilcUInt8 sid);
+ *
+ * DESCRIPTION
+ *
+ * Sets new Security ID to the packet stream indicated by `stream'. This
+ * is called only if the IV Included property was set to the stream
+ * by calling silc_packet_stream_set_iv_included. This function sets
+ * new Security ID to the stream which is then included in the ciphertext
+ * of a packet. The `sid' must be 0 when it is set for the very first
+ * time and must be increased by one after each rekey. This function must
+ * be called every time new keys are added to the stream after a rekey.
+ *
+ * If this function is called when the IV Included property has not been
+ * set to the stream the `sid' will be ignored. Returns FALSE if the
+ * IV Included has not been set, TRUE otherwise.
+ *
+ ***/
+SilcBool silc_packet_set_sid(SilcPacketStream stream, SilcUInt8 sid);
/****f* silccore/SilcPacketAPI/silc_packet_send
*
* SYNOPSIS
*
- * bool silc_packet_send(SilcPacketStream stream,
- * SilcPacketType type, SilcPacketFlags flags,
- * const unsigned char *data, SilcUInt32 data_len);
+ * SilcBool silc_packet_send(SilcPacketStream stream,
+ * SilcPacketType type, SilcPacketFlags flags,
+ * const unsigned char *data,
+ * SilcUInt32 data_len);
*
* DESCRIPTION
*
* Send `data' of length of `data_len' to the packet stream indicated by
* `stream'. If ciphers and HMACs were set using silc_packet_set_ciphers
* and silc_packet_set_hmacs the packet will be encrypted and MAC will be
- * generated for it. If silc_packet_set_ids was used to set source and
+ * computed for it. If silc_packet_set_ids was used to set source and
* destination ID for the packet stream those IDs are used in the
* packet. If IDs have not been set and they need to be provided then
* silc_packet_send_ext function should be used. Otherwise, the packet
- * will not have IDs set at all.
+ * will not have IDs set at all. Returns FALSE if packet could not be
+ * sent.
*
***/
-bool silc_packet_send(SilcPacketStream stream,
- SilcPacketType type, SilcPacketFlags flags,
- const unsigned char *data, SilcUInt32 data_len);
+SilcBool silc_packet_send(SilcPacketStream stream,
+ SilcPacketType type, SilcPacketFlags flags,
+ const unsigned char *data, SilcUInt32 data_len);
/****f* silccore/SilcPacketAPI/silc_packet_send_ext
*
* SYNOPSIS
*
- * bool
+ * SilcBool
* silc_packet_send_ext(SilcPacketStream stream,
* SilcPacketType type, SilcPacketFlags flags,
* SilcIdType src_id_type, void *srd_id,
*
* DESCRIPTION
*
- * This function can be used to specificly set different parameters of
- * the SILC packet to be sent to the stream indicated by `stream'. This
- * function can be used to set specific IDs, cipher and HMAC to be used
- * in packet creation. If `truelen' is provided that value is put to the
- * SILC packet's truelen field, if it is zero the routine will calculate
- * the truelen field for the packet. If `padlen' is provided that value
- * will be the length of the padding for the packet, if zero the routine
- * will calculate necessary amount of padding for the packet. This
- * function can be used when specific ciphers, HMACs and IDs has not been
- * set for the stream, or setting them for the stream is not suitable.
+ * Same as silc_packet_send but with this function different sending
+ * parameters can be sent as argument. This function can be used to
+ * set specific IDs, cipher and HMAC to be used in packet sending,
+ * instead of the ones saved in the `stream'. If any of the extra
+ * pointers are NULL, default values set to the stream will apply.
*
***/
-bool silc_packet_send_ext(SilcPacketStream stream,
- SilcPacketType type, SilcPacketFlags flags,
- SilcIdType src_id_type, void *src_id,
- SilcIdType dst_id_type, void *dst_id,
- const unsigned char *data, SilcUInt32 data_len,
- SilcCipher cipher, SilcHmac hmac);
+SilcBool silc_packet_send_ext(SilcPacketStream stream,
+ SilcPacketType type, SilcPacketFlags flags,
+ SilcIdType src_id_type, void *src_id,
+ SilcIdType dst_id_type, void *dst_id,
+ const unsigned char *data, SilcUInt32 data_len,
+ SilcCipher cipher, SilcHmac hmac);
+
+/****f* silccore/SilcPacketAPI/silc_packet_wait
+ *
+ * SYNOPSIS
+ *
+ * void *silc_packet_wait_init(SilcPacketStream stream, ...);
+ *
+ * DESCRIPTION
+ *
+ * Initializes a packet waiter for the packet stream `stream' and
+ * for the variable argument list of packet types. The function
+ * silc_packet_wait can be used to block the thread until a packet
+ * has been received. This function is used to initialize the waiting
+ * and to give the list of packet types that caller wish to receive.
+ * The variable argument list must end with -1. To receive all
+ * packets use SILC_PACKET_ANY. Returns a context that must be given
+ * to the silc_packet_wait function as argument. Returns NULL on
+ * error. To uninitialize the waiting call silc_packet_wait_uninit.
+ *
+ * NOTES
+ *
+ * Note that packets may be available immediately after calling this
+ * function and they will be buffered, until silc_packet_wait is called.
+ *
+ * EXAMPLE
+ *
+ * void *waiter;
+ *
+ * // Will wait for private message packets
+ * waiter = silc_packet_wait_init(stream,
+ * SILC_PACKET_PRIVATE_MESSAGE, -1);
+ *
+ *
+ ***/
+void *silc_packet_wait_init(SilcPacketStream stream, ...);
+
+/****f* silccore/SilcPacketAPI/silc_packet_wait
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_wait_uninit(void *waiter, SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Uninitializes the waiting context. This may be called also from
+ * another thread while other thread is waiting for packets. This will
+ * inform the waiting thread to stop waiting.
+ *
+ ***/
+void silc_packet_wait_uninit(void *waiter, SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_wait
+ *
+ * SYNOPSIS
+ *
+ * int silc_packet_wait(void *waiter, int timeout,
+ * SilcPacket *return_packet)
+ *
+ * DESCRIPTION
+ *
+ * A special function that can be used to wait for a packet to arrive.
+ * This function will block the calling process or thread until either
+ * a packet is received into the `return_packet' pointer or the specified
+ * timeout value `timeout', which is in milliseconds, will expire. If
+ * the timeout is 0, no timeout exist. Before calling this function the
+ * silc_packet_wait_init must be called. The caller is responsible for
+ * freeing the returned packet with silc_packet_free.
+ *
+ * This function can be used for example from a thread that wants to
+ * block until SILC packet has been received.
+ *
+ * Returns 1 when packet was received, 0 if timeout occurred and -1 if
+ * error occurred.
+ *
+ * EXAMPLE
+ *
+ * static int foo_read_data(FooContext c)
+ * {
+ * SilcPacket packet;
+ * void *waiter;
+ * ...
+ *
+ * // Will wait for private message packets
+ * if (c->initialized == FALSE) {
+ * waiter = silc_packet_wait_init(stream,
+ * SILC_PACKET_PRIVATE_MESSAGE, -1);
+ * c->initialized = TRUE;
+ * }
+ *
+ * ...
+ * // Wait here until private message packet is received
+ * if ((silc_packet_wait(waiter, 0, &packet)) < 0)
+ * return -1;
+ *
+ * ... process packet ...
+ *
+ * return 1;
+ * }
+ *
+ ***/
+int silc_packet_wait(void *waiter, int timeout, SilcPacket *return_packet);
/****f* silccore/SilcPacketAPI/silc_packet_free
*
* SYNOPSIS
*
- * void silc_packet_free(SilcPacketEngine engine, SilcPacket packet);
+ * void silc_packet_free(SilcPacket packet);
*
* DESCRIPTION
*
* This function is used to free the SilcPacket pointer that application
* receives in the SilcPacketReceive callback. Application must free
- * the packet.
+ * the packet if it takes it in to processing.
*
***/
-void silc_packet_free(SilcPacketEngine engine, SilcPacket packet);
+void silc_packet_free(SilcPacket packet);
#endif /* SILCPACKET_H */
projects / silc.git / blobdiff