The following functions are provided by the Prosody DTLS processing API:
| API call | W | Description |
|---|---|---|
| sm_dtlsrx_create() | Create a DTLS[rx] endpoint | |
| sm_dtlsrx_destroy() | Destroy a previously allocated DTLS[rx] | |
| sm_dtlsrx_get_event() | Obtain an event for a DTLS[rx] | |
| sm_dtlsrx_get_packet() | Read a packet from a DTLS[rx] | |
| sm_dtlsrx_status() | Determine DTLS[rx] status | |
| sm_dtlsrx_stop() | Instructs a DTLS[rx] to stop processing DTLS | |
| sm_dtlstx_config() | Configure the basic options for DTLS[tx] to use IPv4 | |
| sm_dtlstx_config_ipv6() | Configure the basic options for a DTLS[tx] to use IPv6 | |
| sm_dtlstx_config_notify() | Configure the packet cpapcity notifications for a DTLS[tx] | |
| sm_dtlstx_create() | Create a DTLS[tx] endpoint | |
| sm_dtlstx_destroy() | Destroy a previously allocated DTLS[tx] | |
| sm_dtlstx_get_event() | Obtain an event for a DTLS[tx] | |
| sm_dtlstx_send_packet() | Pass a packet to a DTLS[tx] for sending | |
| sm_dtlstx_status() | Determine DTLS[tx] status | |
| sm_dtlstx_stop() | Instructs a DTLS[tx] to stop sending DTLS | |
| sm_vmprx_config_dtls() | Configure a VMP[rx] to pass DTLS packets to a DTLS[rx] |
This document is also available as separate pages for each function.
int sm_dtlsrx_create(struct sm_dtlsrx_create_parms *dtlsrxp)
typedef struct sm_dtlsrx_create_parms {
tSMDTLSrxId dtlsrx; /* out */
tSMModuleId module; /* in */
} SM_DTLSRX_CREATE_PARMS;
Allocates, on a specific module, a new DTLS[rx] to process incoming DTLS packets. If the call completes successfully, the parameter dtlsrx will be set to the identifier for that dtlsrx.
Requires the module dtlsrx to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlsrx_destroy(tSMDTLSrxId dtlsrx)
Destroys dtlsrx and invalidates the tSMDTLSrxId.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlsrx_get_event(struct sm_dtlsrx_event_parms *eventp)
typedef struct sm_dtlsrx_event_parms {
tSMDTLSrxId dtlsrx; /* in */
tSMEventId event; /* out */
} SM_DTLSRX_EVENT_PARMS;
If the call completes successfully event will hold a pointer to the tSMEventId belonging to dtlsrx. The tSMEventId is valid until the DTLS[rx] is destroyed using sm_dtlsrx_destroy(). This event will be signalled when a status change occurs on the DTLS[rx]. When the event is signalled the user must call sm_dtlsrx_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlsrx_get_packet(struct sm_dtlsrx_get_packet_parms *readp)
typedef struct sm_dtlsrx_get_packet_parms {
tSMDTLSrxId dtlsrx; /* in */
char *data; /* in */
tSM_INT max_length; /* in */
tSM_INT packet_length; /* out */
} SM_DTLSRX_GET_PACKET_PARMS;
Attempt to read a packet from a DTLS[rx].
Requires the module dtlsrx to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlsrx_status(struct sm_dtlsrx_status_parms *statusp)
typedef struct sm_dtlsrx_status_parms {
tSMDTLSrxId dtlsrx; /* in */
enum kSMDTLSrxStatus {
kSMDTLSrxStatusRunning,
kSMDTLSrxStatusStopped,
kSMDTLSrxStatusHasPacket,
kSMDTLSrxStatusOverrun,
} status; /* out */
} SM_DTLSRX_STATUS_PARMS;
Returns the current status of the DTLS[rx] or an error to indicate that an error has occurred.
When the event, obtained from sm_dtlsrx_get_event(), is signalled the user must call this function to determine the nature of the status change. The change in status may indicate that an error occurred whilst processing a user request or it may be notifiying the user of a change to the previous state of the DTLS[rx].
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlsrx_stop(struct sm_dtlsrx_stop_parms *stopp)
typedef struct sm_dtlsrx_stop_parms {
tSMDTLSrxId dtlsrx; /* in */
} SM_DTLSRX_STOP_PARMS;
Requests that a DTLS[rx] stops executing. The user will be notified that a DTLS[rx] has terminated by a final status event. Once the final status notification has been received the DTLS[rx] can be destroyed using sm_dtlsrx_destroy().
Once the DTLS[rx] has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_dtlsrx_destroy() is called.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_config(struct sm_dtlstx_config_parms *configp)
typedef struct sm_dtlstx_config_parms {
tSMDTLStxId dtlstx; /* in */
SOCKADDR_IN destination; /* in */
SOCKADDR_IN source; /* in */
} SM_DTLSTX_CONFIG_PARMS;
Configures a DTLS[tx] to send DTLS packets to a device with the specified IPv4 address.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_config_ipv6(struct sm_dtlstx_config_ipv6_parms *configp)
typedef struct sm_dtlstx_config_ipv6_parms {
tSMDTLStxId dtlstx; /* in */
SOCKADDR_IN6 destination; /* in */
SOCKADDR_IN6 source; /* in */
} SM_DTLSTX_CONFIG_IPV6_PARMS;
Configures a DTLS[tx] to send DTLS packets to a device with the specified IPv6 address.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_config_notify(struct sm_dtlstx_config_notify_parms *configp)
typedef struct sm_dtlstx_config_notify_parms {
tSMDTLStxId dtlstx; /* in */
tSM_UT32 packet_length; /* in */
tSM_INT no_capacity_event; /* in */
} SM_DTLSTX_CONFIG_NOTIFY_PARMS;
Configures when a DTLS[tx] reports capacity for another packet to be queued. It also configures whether the event should be set when there is capacity for another packet.
When
no_capacity_event
is zero, the event is set when
sm_dtlstx_status()
will report kSMDTLStxStatusHasCapacity. If it
is non-zero, the event will not be set unless a different status
will be reported.
kSMDTLStxStatusHasCapacity.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_create(struct sm_dtlstx_create_parms *dtlstxp)
typedef struct sm_dtlstx_create_parms {
tSMDTLStxId dtlstx; /* out */
tSMModuleId module; /* in */
} SM_DTLSTX_CREATE_PARMS;
Allocates, on a specific module, a new DTLS[tx] to transmit DTLS packets to a remote device.
If the call completes successfully, the parameter dtlstx will be set to the identifier for that DTLS[tx].
Requires the module dtlstx to have been downloaded.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_destroy(tSMDTLStxId dtlstx)
Destroys dtlstx and invalidates the tSMDTLStxId.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_get_event(struct sm_dtlstx_event_parms *eventp)
typedef struct sm_dtlstx_event_parms {
tSMDTLStxId dtlstx; /* in */
tSMEventId event; /* out */
} SM_DTLSTX_EVENT_PARMS;
If the call completes successfully event will hold a pointer to the tSMEventId belonging to dtlstx. The tSMEventId is valid until the DTLS[tx] is destroyed using sm_dtlstx_destroy(). This event will be signalled when a status change occurs on the DTLS[tx]. When the event is signalled the user must call sm_dtlstx_status() to discover the nature of the status change.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_send_packet(struct sm_dtlstx_send_packet_parms *packetp)
typedef struct sm_dtlstx_send_packet_parms {
tSMDTLStxId dtlstx; /* in */
char *data; /* in */
tSM_INT packet_length; /* in */
} SM_DTLSTX_SEND_PACKET_PARMS;
Sends a packet using a DTLS[tx].
Requires the module dtlstx to have been downloaded.
0 if call completed successfully, otherwise a standard error.
int sm_dtlstx_status(struct sm_dtlstx_status_parms *statusp)
typedef struct sm_dtlstx_status_parms {
tSMDTLStxId dtlstx; /* in */
enum kSMDTLStxStatus {
kSMDTLStxStatusRunning,
kSMDTLStxStatusStopped,
kSMDTLStxStatusHasCapacity,
} status; /* out */
} SM_DTLSTX_STATUS_PARMS;
Returns the current status of the DTLS[tx] or an error to indicate that a problem occurred during start-up.
0 if call completed successfully, otherwise a standard error such as:
int sm_dtlstx_stop(struct sm_dtlstx_stop_parms *stopp)
typedef struct sm_dtlstx_stop_parms {
tSMDTLStxId dtlstx; /* in */
} SM_DTLSTX_STOP_PARMS;
Requests that a DTLS[tx] stops executing. The user will be notified that a DTLS[tx] has terminated by a final status event. Once the final status notification has been received the DTLS[tx] can be destroyed using sm_dtlstx_destroy().
Once the DTLS[tx] has stopped the event should no longer be used to wait for status notifications as it will be signalled permanently. The event is invalidated when sm_dtlstx_destroy() is called.
0 if call completed successfully, otherwise a standard error such as:
int sm_vmprx_config_dtls(struct sm_vmprx_config_dtls_parms *configp)
typedef struct sm_vmprx_config_dtls_parms {
tSMVMPrxId vmprx; /* in */
tSMDTLSrxId dtlsrx; /* in */
tSM_INT use_RTCP_port; /* in */
} SM_VMPRX_CONFIG_DTLS_PARMS;
Configures a VMP[rx] to pass incoming DTLS packets to a DTLS[rx].
Requires the modules dtlsrx and vmprx to have been downloaded.
kSMNullDTLSrxId
then the VMP[rx] will no longer pass on DTLS packets.
0 if call completed successfully, otherwise a standard error such as:
These functions constitute the Prosody DTLS processing API.