+
+/****f* silccore/SilcPacketAPI/silc_packet_engine_start
+ *
+ * SYNOPSIS
+ *
+ * SilcPacketEngine
+ * 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 `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.
+ *
+ * NOTES
+ *
+ * The packet engine is thread safe. You can use one packet engine in
+ * multi threaded application.
+ *
+ ***/
+SilcPacketEngine
+silc_packet_engine_start(SilcRng rng, SilcBool router,
+ SilcPacketCallbacks *callbacks,
+ void *callback_context);
+
+/****f* silccore/SilcPacketAPI/silc_packet_engine_stop
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_engine_stop(SilcPacketEngine engine);
+ *
+ * DESCRIPTION
+ *
+ * Stop the packet engine. No new packets can be sent or received after
+ * calling this, and the `engine' will become invalid.
+ *
+ ***/
+void silc_packet_engine_stop(SilcPacketEngine engine);
+
+/****f* silccore/SilcPacketAPI/silc_packet_stream_create
+ *
+ * SYNOPSIS
+ *
+ * SilcPacketStream silc_packet_stream_create(SilcPacketEngine engine,
+ * SilcSchedule schedule,
+ * SilcStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Create new packet stream and use the `stream' as underlaying stream.
+ * Usually the `stream' would be a socket stream, but it can be any
+ * stream. After this function returns, packets can immediately be
+ * sent to or received from the stream.
+ *
+ * NOTES
+ *
+ * SilcPacketStream cannot be used with silc_stream_* routines (such as
+ * silc_stream_read and silc_stream_write) because of its special nature.
+ * Use the silc_packet_send and the silc_packet_send_ext to send packets.
+ * 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 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
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_stream_destroy(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Destroy packet stream and the underlaying stream. This will also
+ * send end of stream to the underlaying stream.
+ *
+ ***/
+void silc_packet_stream_destroy(SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_stream_set_router
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_stream_set_router(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * 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.
+ *
+ ***/
+void silc_packet_stream_set_router(SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_streamer_create
+ *
+ * SYNOPSIS
+ *
+ * SilcStream silc_packet_streamer_create(SilcPacketStream stream,
+ * SilcPacketType packet_type,
+ * SilcPacketFlags packet_flags);
+ *
+ * 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.
+ *
+ ***/
+SilcStream silc_packet_streamer_create(SilcPacketStream stream,
+ SilcPacketType packet_type,
+ SilcPacketFlags packet_flags);
+
+/****f* silccore/SilcPacketAPI/silc_packet_streamer_destroy
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_streamer_destroy(SilcStream 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.
+ *
+ ***/
+void silc_packet_streamer_destroy(SilcStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_stream_get_stream
+ *
+ * SYNOPSIS
+ *
+ * SilcStream silc_packet_stream_get_stream(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * 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 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_link
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_stream_link(SilcPacketStream stream,
+ * SilcPacketCallbacks *callbacks,
+ * void *callback_context,
+ * int priority, ...);
+ *
+ * DESCRIPTION
+ *
+ * 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);
+ *
+ ***/
+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
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_stream_ref(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Increase reference counter for the stream indicated by `stream'. This
+ * can be used to take a reference for the stream. To unreference the
+ * stream call silc_packet_stream_unref function.
+ *
+ ***/
+void silc_packet_stream_ref(SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_stream_unref
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_stream_unref(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Decrease reference counter for the stream indicated by `stream'. If
+ * the counter hits zero the stream will be destroyed automatically.
+ *
+ ***/
+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 *stream_context);
+ *
+ * DESCRIPTION
+ *
+ * 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, and this context as the `stream_context' argument.
+ *
+ ***/
+void silc_packet_set_context(SilcPacketStream stream, void *stream_context);
+
+/****f* silccore/SilcPacketAPI/silc_packet_get_context
+ *
+ * SYNOPSIS
+ *
+ * void *silc_packet_get_context(SilcPacketStream stream);
+ *
+ * DESCRIPTION
+ *
+ * Returns the current set application context, or NULL if none is set.
+ *
+ ***/
+void *silc_packet_get_context(SilcPacketStream stream);
+
+/****f* silccore/SilcPacketAPI/silc_packet_set_ciphers
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_set_ciphers(SilcPacketStream stream, SilcCipher send,
+ * SilcCipher receive);
+ *
+ * DESCRIPTION
+ *
+ * Set ciphers to be used to encrypt sent packets, and decrypt received
+ * packets. This can be called multiple times to change the ciphers.
+ * In this case if old cipher is set it will be freed. If ciphers are
+ * not set packets will not be encrypted or decrypted.
+ *
+ ***/
+void silc_packet_set_ciphers(SilcPacketStream stream, SilcCipher send,
+ SilcCipher receive);
+
+/****f* silccore/SilcPacketAPI/silc_packet_get_ciphers
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_get_ciphers(SilcPacketStream stream,
+ * SilcCipher *send,
+ * SilcCipher *receive);
+ *
+ * DESCRIPTION
+ *
+ * Returns the pointers of current ciphers from the `stream'. Returns
+ * FALSE if ciphers are not set.
+ *
+ ***/
+SilcBool silc_packet_get_ciphers(SilcPacketStream stream, SilcCipher *send,
+ SilcCipher *receive);
+
+/****f* silccore/SilcPacketAPI/silc_packet_set_hmacs
+ *
+ * SYNOPSIS
+ *
+ * void silc_packet_set_hmacs(SilcPacketStream stream, SilcHmac send,
+ * SilcHmac receive);
+ *
+ * DESCRIPTION
+ *
+ * Set HMACs to be used to create MACs for sent packets and to check
+ * MAC for received packets. This can be called multiple times to change
+ * the HMACs. In this case if old HMAC is set it will be freed. If
+ * HMACs are not set MACs are not generated or verified for packets.
+ *
+ ***/
+void silc_packet_set_hmacs(SilcPacketStream stream, SilcHmac send,
+ SilcHmac receive);
+
+/****f* silccore/SilcPacketAPI/silc_packet_get_hmacs
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
+ * SilcHmac *receive);
+ *
+ * DESCRIPTION
+ *
+ * Returns the pointers of current HMACs from the `stream'. Returns
+ * FALSE if HMACs are not set.
+ *
+ ***/
+SilcBool silc_packet_get_hmacs(SilcPacketStream stream, SilcHmac *send,
+ SilcHmac *receive);
+
+/****f* silccore/SilcPacketAPI/silc_packet_set_ids
+ *
+ * SYNOPSIS
+ *
+ * SilcBool silc_packet_set_ids(SilcPacketStream stream,
+ * SilcIdType src_id_type, const void *src_id
+ * SilcIdType dst_id_type, const void *dst_id);
+ *
+ * DESCRIPTION
+ *
+ * Set the source ID and destinaion 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.
+ * In this case they can be omitted when sending packets to the stream.
+ * It is also possible to set only source or destination 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_send
+ *
+ * SYNOPSIS
+ *
+ * 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
+ * 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. Returns FALSE if packet could not be
+ * sent.
+ *
+ ***/
+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
+ *
+ * SilcBool
+ * silc_packet_send_ext(SilcPacketStream stream,
+ * SilcPacketType type, SilcPacketFlags flags,
+ * SilcIdType src_id_type, void *srd_id,
+ * SilcIdType dst_id_type, void *dst_id,
+ * const unsigned char *data, SilcUInt32 data_len,
+ * SilcCipher cipher, SilcHmac hmac);
+ *
+ * DESCRIPTION
+ *
+ * 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'.
+ *
+ ***/
+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_free
+ *
+ * SYNOPSIS
+ *
+ * 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 if it takes it in to processing.
+ *
+ ***/
+void silc_packet_free(SilcPacket packet);
+
+#endif /* SILCPACKET_H */