Author: Pekka Riikonen <priikone@silcnet.org>
- Copyright (C) 1997 - 2007 Pekka Riikonen
+ Copyright (C) 1997 - 2014 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
#ifndef SILCPACKET_H
#define SILCPACKET_H
-/* XXX many of these could go to silcpacket_i.h */
-
/* Maximum packet length */
#define SILC_PACKET_MAX_LEN 0xffff
#define SILC_PACKET_FLAG_ACK 0x10 /* Acknowledge packet */
/* Impelemntation specific flags */
-#define SILC_PACKET_FLAG_LONG_PAD 0x12 /* Use maximum padding */
+#define SILC_PACKET_FLAG_LONG_PAD 0x20 /* Use maximum padding */
/***/
/****s* silccore/SilcPacketAPI/SilcPacketEngine
* from the actual stream. It can retrieve the underlaying stream from
* the packet stream by calling silc_packet_stream_get_stream function.
*
+ * You may retrieve string version of the SilcPacketError by calling
+ * silc_packet_error_string.
+ *
* SOURCE
*/
typedef enum {
***/
SilcPacketEngine
silc_packet_engine_start(SilcRng rng, SilcBool router,
- SilcPacketCallbacks *callbacks,
+ const SilcPacketCallbacks *callbacks,
void *callback_context);
/****f* silccore/SilcPacketAPI/silc_packet_engine_stop
***/
void silc_packet_engine_stop(SilcPacketEngine engine);
+/****f* silccore/SilcPacketAPI/silc_packet_error_string
+ *
+ * SYNOPSIS
+ *
+ * const char *silc_packet_error_string(SilcPacketError error);
+ *
+ * DESCRIPTION
+ *
+ * Return the packet error as string.
+ *
+ ***/
+const char *silc_packet_error_string(SilcPacketError error);
+
+/****f* silccore/SilcPacketAPI/silc_packet_engine_get_streams
+ *
+ * SYNOPSIS
+ *
+ * SilcDList silc_packet_engine_get_streams(SilcPacketEngine engine);
+ *
+ * DESCRIPTION
+ *
+ * Returns list of packet streams added to the packet engine. The caller
+ * must free the list with silc_packet_engine_free_streams_list.
+ *
+ * NOTES
+ *
+ * This function may also return disconnected and destroyed streams. The
+ * caller should use silc_packet_stream_is_valid to check if the stream
+ * is valid.
+ *
+ ***/
+SilcDList silc_packet_engine_get_streams(SilcPacketEngine engine);
+
+/****f* silccore/SilcPacketAPI/silc_packet_engine_free_streams_list
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_engine_free_streams_list(SilcDList streams);
+ *
+ * DESCRIPTION
+ *
+ * Free's the streams list returned by silc_packet_engine_get_streams.
+ *
+ ***/
+void silc_packet_engine_free_streams_list(SilcDList streams);
+
/****f* silccore/SilcPacketAPI/silc_packet_stream_create
*
* SYNOPSIS
* stream. After this function returns, packets can immediately be
* sent to and received from the stream.
*
+ * The `stream' will be owned by the packet stream and will be closed
+ * and destroyed when the packet stream is destroyed. If the packet
+ * stream creation fails the `stream' is left intact.
+ *
* NOTES
*
* SilcPacketStream cannot be used with silc_stream_* routines (such as
SilcUInt16 remote_port,
SilcPacket packet);
+/****f* silccore/SilcPacketAPI/silc_packet_stream_inject
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_stream_inject(SilcPacketStream stream,
+ * SilcPacket packet);
+ *
+ * DESCRIPTION
+ *
+ * This function can be used to inject the `packet' to the given
+ * packet `stream'. The packet will appear in the packet stream's
+ * packet handler(s). If this returns FALSE the packet was not
+ * injected.
+ *
+ ***/
+SilcBool silc_packet_stream_inject(SilcPacketStream stream,
+ SilcPacket packet);
+
/****f* silccore/SilcPacketAPI/silc_packet_stream_destroy
*
* SYNOPSIS
***/
void silc_packet_stream_destroy(SilcPacketStream stream);
+/****f* silccore/SilcPacketAPI/silc_packet_stream_is_valid
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_stream_is_valid(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Returns TRUE if the packet stream indicated by `stream' is valid and
+ * has not been disconnected or destroyed.
+ *
+ ***/
+SilcBool silc_packet_stream_is_valid(SilcPacketStream stream);
+
/****f* silccore/SilcPacketAPI/silc_packet_stream_set_router
*
* SYNOPSIS
*
***/
SilcBool silc_packet_stream_link(SilcPacketStream stream,
- SilcPacketCallbacks *callbacks,
+ const SilcPacketCallbacks *callbacks,
void *callback_context,
int priority, ...);
*
***/
void silc_packet_stream_unlink(SilcPacketStream stream,
- SilcPacketCallbacks *callbacks,
+ const SilcPacketCallbacks *callbacks,
void *callback_context);
/****f* silccore/SilcPacketAPI/SilcPacketWrapCoder
*
* DESCRIPTION
*
- * The encoder/decoder callback for silc_packet_stream_wrap. If the
- * `status' is SILC_STREAM_CAN_WRITE then additional data can be added
- * to `buffer'. It is added before the data that is written with
- * silc_stream_write. The silc_buffer_enlarge should be called to verify
- * there is enough room in `buffer' before adding data to it. The `buffer'
- * must not be freed.
+ * The encoder/decoder callback for silc_packet_stream_wrap.
*
- * If the `status' is SILC_STREAM_CAN_READ then data from the `buffer'
- * may be read before it is passed to readed when silc_stream_read is
- * called. The `buffer' may be advanced also to hide data in it.
+ * If the `status' is SILC_STREAM_CAN_WRITE then additional data can
+ * be added to `buffer' which contains the data that is being written
+ * to the stream. There is at least 16 bytes of free space in head
+ * space of the buffer in case new headers need to be added.
+ * The silc_buffer_enlarge should be called to verify that there is
+ * enough room before adding data to it. The `buffer' must not be freed.
+ * If the return value is FALSE the encoding failed and the packet is
+ * not sent at all and the stream will receive error. Return TRUE if
+ * the encoding succeeded.
*
- * This function returns FALSE in case of error.
+ * If the `status' is SILC_STREAM_CAN_READ then data from the `buffer'
+ * may be read before it is passed to reader when silc_stream_read is
+ * called. The `buffer' may be advanced also to hide data in it. If
+ * return value is FALSE the decoding failed (or the packet is ignored)
+ * and the packet will not be processed by the wrapped packet stream.
+ * If there are other packet streams wanting the same packet, they will
+ * get it, and if not the packet will drop. Return TRUE if decoding
+ * succeeded.
*
***/
typedef SilcBool (*SilcPacketWrapCoder)(SilcStream stream,
* SilcPacketType type,
* SilcPacketFlags flags,
* SilcBool blocking_mode,
+ * SilcIdType src_id_type, void *src_id,
+ * SilcIdType dst_id_type, void *dst_id,
* SilcPacketWrapCoder coder,
* void *context);
*
* once returns one complete SILC packet data payload (which is of type of
* `type').
*
+ * If src_id and/or dst_id are set they will be used as the ids in the
+ * sent SILC packets. If the dst_id is set then the stream will receive
+ * packets only originating from that id.
+ *
* The `coder' is optional encoder/decoder callback which the packet engine
* will call if it is non-NULL. It can be used to encode additional data
* into each packet when silc_stream_write is called or decode data before
SilcPacketType type,
SilcPacketFlags flags,
SilcBool blocking_mode,
+ SilcIdType src_id_type, void *src_id,
+ SilcIdType dst_id_type, void *dst_id,
SilcPacketWrapCoder coder,
void *context);
*
* DESCRIPTION
*
- * Set the source ID and destinaion ID to be used when sending packets to
+ * Set the source ID and destination ID to be used when sending packets to
* this packet stream. The IDs to be used for a packet stream can be
* overridden when sending packets. However, if the IDs do not ever change
* for the packet stream it is recommended they are set using this function.
SilcIdType src_id_type, const void *src_id,
SilcIdType dst_id_type, const void *dst_id);
+/****f* silccore/SilcPacketAPI/silc_packet_get_ids
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_get_ids(SilcPacketStream stream,
+ * SilcBool *src_id_set, SilcID *src_id,
+ * SilcBool *dst_id_set, SilcID *dst_id);
+ *
+ * DESCRIPTION
+ *
+ * Returns source and destination IDs from the packet stream. The
+ * `src_id_set' is set to TRUE if the source ID was returned. The
+ * `dst_id_set' is set to TRUE if the destination ID was returned.
+ *
+ ***/
+SilcBool silc_packet_get_ids(SilcPacketStream stream,
+ SilcBool *src_id_set, SilcID *src_id,
+ SilcBool *dst_id_set, SilcID *dst_id);
+
/****f* silccore/SilcPacketAPI/silc_packet_set_sid
*
* SYNOPSIS
SilcIdType dst_id_type, void *dst_id,
SilcCipher cipher, SilcHmac hmac, ...);
-/****f* silccore/SilcPacketAPI/silc_packet_wait
+/****f* silccore/SilcPacketAPI/silc_packet_wait_init
*
* SYNOPSIS
*
- * void *silc_packet_wait_init(SilcPacketStream stream, ...);
+ * void *silc_packet_wait_init(SilcPacketStream stream,
+ * const SilcID *source_id, ...);
*
* 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.
+ * 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.
+ * If the `source_id' is non-NULL then only packets of the specified
+ * type from the specified `source_id' are received. If it is NULL
+ * then the packet source is ignored.
+ *
+ * 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
*
* void *waiter;
*
* // Will wait for private message packets
- * waiter = silc_packet_wait_init(stream,
+ * waiter = silc_packet_wait_init(stream, NULL,
* SILC_PACKET_PRIVATE_MESSAGE, -1);
*
- *
***/
-void *silc_packet_wait_init(SilcPacketStream stream, ...);
+void *silc_packet_wait_init(SilcPacketStream stream,
+ const SilcID *source_id, ...);
/****f* silccore/SilcPacketAPI/silc_packet_wait_uninit
*
projects / silc.git / blobdiff