Callback Framework#
This section provides a reference to Wi-Fi API callback handling functions.
Note
- Stack overflows may occur if you invoke functions or use your own variables or data structures while handling callbacks. Please configure the stack size by modifying the pre-processor macro - SL_SI91X_EVENT_HANDLER_STACK_SIZEas per your application's requirements. See here for the instructions for modifying a pre-processor macro.
- Event/Callback handlers must not contain function calls or code which can block or delay the execution of the event/callback handler as it causes all the other events to queue up and delay the execution of other events since all the events are invoked and handled from a single thread. 
- Do not call any synchronous SDK APIs from within the Event/Callback handlers. 
Typedefs#
Generic callback for Wi-Fi group events of type sl_wifi_event_group_t.
Callback for SL_WIFI_SCAN_RESULT_EVENTS group event of type sl_wifi_event_group_t.
Callback for SL_WIFI_STATS_RESPONSE_EVENTS group events of type sl_wifi_event_group_t.
Callback for SL_WIFI_JOIN_EVENTS group events of type sl_wifi_event_group_t.
Callback for SL_WIFI_TWT_RESPONSE_EVENTS group events.
Callback for SL_WIFI_TRANSCEIVER_EVENTS group events.
Functions#
Register a callback for a selected event group.
Default Wi-Fi event handler to be passed to sl_wifi_init.
Register a callback for the SL_WIFI_SCAN_RESULT_EVENTS group event from sl_wifi_event_group_t.
Register a callback for SL_WIFI_JOIN_EVENTS group event from sl_wifi_event_group_t.
Register a callback for SL_WIFI_TWT_RESPONSE_EVENTS group event from sl_wifi_event_group_t.
Register a callback for SL_WIFI_STATS_RESPONSE_EVENTS group event from sl_wifi_event_group_t.
Register a callback for SL_WIFI_TRANSCEIVER_EVENTS group event of tye sl_wifi_event_group_t.
Macros#
Generic macro for callback functions to check if the event has failed.
Typedef Documentation#
sl_wifi_callback_function_t#
sl_wifi_callback_function_t )(sl_wifi_event_t event, void *data, uint32_t data_length, void *optional_arg)
Generic callback for Wi-Fi group events of type sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| N/A | event | Wi-Fi event of type sl_wifi_event_t. This parameter indicates the specific Wi-Fi event that triggered the callback. | |
| N/A | data | Pointer to the data received. The type and content of this data depend on the specific event. | |
| N/A | data_length | Length of the data received in bytes. | |
| N/A | optional_arg | Optional user-provided argument passed in sl_wifi_set_callback. This parameter allows the user to pass additional context or information to the callback function. | 
This typedef defines a callback function that handles Wi-Fi events of type sl_wifi_event_t. The callback is invoked when a Wi-Fi event occurs, providing the event details and any associated data.
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- In case of event failure, the - SL_WIFI_FAIL_EVENT_STATUS_INDICATIONbit is set in the- eventparameter. When this bit is set, the- dataparameter will be of type- sl_status_t, and the- data_lengthparameter can be ignored.
sl_wifi_scan_callback_t#
sl_wifi_scan_callback_t )(sl_wifi_event_t event, sl_wifi_scan_result_t *data, uint32_t data_length, void *optional_arg)
Callback for SL_WIFI_SCAN_RESULT_EVENTS group event of type sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | ||||
|---|---|---|---|---|---|---|---|
| N/A | event | Wi-Fi event of type sl_wifi_event_t. This parameter indicates the specific Wi-Fi event that triggered the callback. 
 | |||||
| N/A | data | Pointer to the scan results of type sl_wifi_scan_result_t. This parameter provides the scan results obtained from the Wi-Fi scan operation. | |||||
| N/A | data_length | Length of the scan results data received in bytes. | |||||
| N/A | optional_arg | Optional user provided argument passed in sl_wifi_set_scan_callback. | 
This typedef defines a callback function that handles Wi-Fi scan result events of type sl_wifi_event_t. The callback is triggered when a Wi-Fi module tries to scan and receive the response, providing the event details and any associated scan results.
- Wi-Fi module must call sl_wifi_start_scan to receive SL_WIFI_SCAN_RESULT_EVENTS event. 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- In case of event failure, SL_WIFI_FAIL_EVENT_STATUS_INDICATION bit is set in the event. When this bit is set, the - dataparameter will be of type- sl_status_t, and the- data_lengthparameter can be ignored.
sl_wifi_stats_callback_t#
sl_wifi_stats_callback_t )(sl_wifi_event_t event, void *data, uint32_t data_length, void *optional_arg)
Callback for SL_WIFI_STATS_RESPONSE_EVENTS group events of type sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| N/A | event | Wi-Fi event of type sl_wifi_event_t that triggered the callback. Individual Wi-Fi events related to SL_WIFI_STATS_RESPONSE_EVENTS is as follows: 
 | |||||||||||||
| N/A | data | Pointer to the payload received. | |||||||||||||
| N/A | data_length | Length of the payload received in bytes. | |||||||||||||
| N/A | optional_arg | Optional user provided argument passed in sl_wifi_set_stats_callback. | 
This typedef defines a callback function that handles Wi-Fi statistics response events of type sl_wifi_event_t. The callback is invoked when a Wi-Fi statistics response event occurs, providing the event details and any associated data.
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- SL_WIFI_STATS_MODULE_STATE_EVENT messages are used to indicate module state to the host. These messages are enabled by setting the 10th bit of the custom feature bitmap in opermode. For the event SL_WIFI_STATS_MODULE_STATE_EVENT response structure refer sl_si91x_module_state_stats_response_t. - state_code of this response (1 byte), indicates the state of the module. - state_codecontains two parts, the upper nibble and lower nibble. The state code is formed by combining the upper and the lower nibbles using a bitwise OR operation, that is, State code = upper nibble | lower nibble For example, if the state code is 82 but is not found in the table, it can be divided as follows: state_code = 80 | 02, where 80 is the upper nibble and 02 is the lower nibble.- The upper nibble indicates the state of the rejoin process. The following table documents the possible values of the upper nibble of the state_code. - Module state code - upper nibble - Description - Scan Trigger (State I) - 0x00 - Startup (Initial state or idle state). - Indicates the reason for the scan - -----------— - -------------------------------------------------------------------------— - triggered. - 0x10 - Beacon Loss (Failover Roam). - -----------— - -------------------------------------------------------------------------— - 0x20 - De-authentication from AP. - ----------------------------------— - -----------— - -------------------------------------------------------------------------— - Scan Result/Decision (State II) - 0x50 - Current AP is best. - Indicates a state change based on - -----------— - ------------------------------------------------------------------------— - the scan result. - 0x60 - Better AP found while roaming. - -----------— - -------------------------------------------------------------------------— - 0x70 - No AP found. - ----------------------------------— - -----------— - -------------------------------------------------------------------------— - Final Connection or Join (State III) - 0x80 - Associated or joined to an Access point. - Indicates the connection state - -----------— - -------------------------------------------------------------------------— - change - 0x90 - Unassociated(Disconnected from host or join failure). 
 
- The lower nibble of state_code indicates the reason for a state change. The table below lists the possible values of the lower nibble of the state_code. - Module state code lower nibble - Description - 0x00 - No reason specified (Initial state or idle state). - 0x01 - No response from AP for authentication request(Authentication denial). - 0x02 - Association denial (Association timeout or Association failure due to unknown reasons). - 0x03 - User configured AP is not present. - 0x05 - Four-way Handshake failure. - 0x06 - Deauthentication from user. - 0x07 - PSK not configured. - 0x08 - key-handshake failure during rejoin/roaming/after connection(Disconnection from supplicant). - 0x09 - Roaming not enabled. 
- Module reason code - Description - 0x00 - No reason specified (Initial state or idle state). - 0x01 - No response from AP for authentication request(Authentication denial). - 0x02 - Association denial (caused by Association timeout or Association failure due to unknown reasons). - 0x03 - User configured AP is not present. - 0x05 - Four-way Handshake failure. - 0x06 - Deauthentication from user. - 0x07 - PSK not configured. - 0x08 - key-handshake failure during rejoin/roaming/after connection(Disconnection from supplicant). - 0x09 - Roaming not enabled - 0x10 - Beacon Loss (Failover Roam). - 0x20 - De-authentication from AP. - 0x28 - TLS CA Cert not present - 0x29 - TLS PRIVATE key not present. - 0x2A - TLS Client Cert not present. - 0x2B - TLS no Cert present. - 0x2C - PEAP CA Cert not present. - 0x2D - Server Cert Invalid Key Type. - 0x2E - Server Intermediate CA Invalid Key Type. - 0x2F - Server Root CA Invalid Key Type. - 0x30 - Client Cert Invalid Key Type. - 0x31 - Client Root CA Invalid Key Type. - 0x37 - Server Cert 4096-bit length support is not enabled. - 0x38 - Server Intermediate CA 4096-bit length support is not enabled. - 0x39 - Server Root CA 4096-bit length support is not enabled. - 0x3A - Client Cert 4096-bit length support is not enabled. - 0x3B - Client Root CA 4096-bit length support is not enabled. - 0x3C - Server Cert Invalid Sign Alg. - 0x3D - Server Intermediate CA Invalid Sign Alg. - 0x3E - Server Root CA Invalid Sign Length. - 0x3F - Client Cert Invalid Sign Alg. - 0x40 - Client Root CA Invalid Sign Length. - 0x41 - Server Intermediate CA not Present. - 0x42 - Server Root CA Parse Error. - 0x43 - Server Intermediate Root CA Parse Error. - 0x44 - Sever Cert Parse Error. - 0x45 - Client Cert Parse Error. - 0x46 - Incorrect Private Key Password. - 0x47 - EAP Failure Received. - 0x48 - Client Cert Bad Date Error. - 0x49 - Server Cert Bad Date Error. - 0x4A - Server Root CA Bad Date Error. - 0x4B - Client Root CA Bad Date Error. - 0x4C - Server Intermediate Root CA Bad Date Error. - 0x4D - Pem Header Error. - 0x4E - Pem Footer Error. - 0x4F - Client Intermediate CA Invalid Sign Length. - 0x50 - Client Intermediate CA Invalid Length. - 0x52 - Client Intermediate CA invalid Key Type. - 0x53 - Pem Error. - 0x54 - Pathlen certificate is Invalid. 
- In addition to the above, the reason code received in the Deauthentication/Disassociation frame from the AP is modified by setting the Most Significant Bit (MSB) of the reason code. If the MSB is set in the reason code, it should be masked with 0x7F to extract the actual reason code received in the Deauthentication/Disassociation frame. Pem Header Error (0x4D) and Pem Footer Error (0x4E) apply only when certificates are loaded individually. If certificates are loaded together in a single file, only the Pem Error (0x53) triggers for any header or footer errors. 
- In case of event failure, the - SL_WIFI_FAIL_EVENT_STATUS_INDICATIONbit is set in the- eventparameter. When this bit is set, the- dataparameter will be of type- sl_status_t, and the- data_lengthparameter can be ignored.
sl_wifi_join_callback_t#
sl_wifi_join_callback_t )(sl_wifi_event_t event, char *data, uint32_t data_length, void *optional_arg)
Callback for SL_WIFI_JOIN_EVENTS group events of type sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
| N/A | event | Wi-Fi event of type sl_wifi_event_t that triggered the callback. | |||||||
| N/A | data | Pointer to the response data received (1 byte). The possible values and their descriptions are as follows: 
 | |||||||
| N/A | data_length | Length of the data received in bytes. This parameter indicates the size of the data buffer pointed to by the  | |||||||
| N/A | optional_arg | Optional user provided argument passed in sl_wifi_set_join_callback. | 
This typedef defines a callback function that handles Wi-Fi join events of type sl_wifi_event_t. The callback is invoked when a Wi-Fi join event occurs, providing the event details and any associated data.
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- This is valid in WiFi client mode only 
- In case of event failure, the - SL_WIFI_FAIL_EVENT_STATUS_INDICATIONbit is set in the- eventparameter. When this bit is set, the- dataparameter will be of type- sl_status_t, and the- data_lengthparameter can be ignored.
sl_wifi_twt_config_callback_t#
sl_wifi_twt_config_callback_t )(sl_wifi_event_t event, sl_si91x_twt_response_t *data, uint32_t data_length, void *optional_arg)
Callback for SL_WIFI_TWT_RESPONSE_EVENTS group events.
| Type | Direction | Argument Name | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| N/A | event | Wi-Fi event of type sl_wifi_event_t that triggered the callback. Individual Wi-Fi events related to SL_WIFI_TWT_RESPONSE_EVENTS is as follows: 
 | |||||||||||||||||||||||||||||
| N/A | data | Pointer to the data received of type sl_si91x_twt_response_t. This parameter provides detailed information about the TWT response event. The structure contains various fields that describe the TWT session parameters and status. | |||||||||||||||||||||||||||||
| N/A | data_length | Length of the data received in bytes. | |||||||||||||||||||||||||||||
| N/A | optional_arg | Optional user provided argument passed in sl_wifi_set_twt_config_callback. | 
This typedef defines a callback function that handles Wi-Fi Target Wake Time (TWT) configuration response events. The callback is invoked when a TWT response event occurs, providing the event details and any associated data.
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- In case of event failure, the - SL_WIFI_FAIL_EVENT_STATUS_INDICATIONbit is set in the- eventparameter. When this bit is set, the- dataparameter will be of type- sl_status_t, and the- data_lengthparameter can be ignored.
sl_wifi_transceiver_callback_t#
sl_wifi_transceiver_callback_t )(sl_wifi_event_t event, void *data, uint32_t data_length, void *optional_arg)
Callback for SL_WIFI_TRANSCEIVER_EVENTS group events.
| Type | Direction | Argument Name | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
| [out] | event | Wi-Fi event of type sl_wifi_event_t. This parameter indicates the specific Wi-Fi event that triggered the callback. Individual Wi-Fi events related to SL_WIFI_TRANSCEIVER_EVENTS are as follows: 
 | |||||||
| [out] | data | 
 | |||||||
| [out] | data_length | Reserved. | |||||||
| [out] | optional_arg | Optional user provided argument passed in sl_wifi_set_transceiver_callback | 
This typedef defines a callback function that handles Wi-Fi transceiver events. The callback is invoked when a transceiver event occurs, providing the event details and any associated data.
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- This API is only supported in Wi-Fi Transceiver opermode (7). 
- In case of event failure, the - SL_WIFI_FAIL_EVENT_STATUS_INDICATIONbit is set in the- eventparameter. When this bit is set, the- dataparameter will be of type- sl_status_t, and the- data_lengthparameter can be ignored.
Function Documentation#
sl_wifi_set_callback#
sl_status_t sl_wifi_set_callback (sl_wifi_event_group_t group, sl_wifi_callback_function_t function, void * optional_arg)
Register a callback for a selected event group.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_event_group_t | [in] | group | Group ID of the event for which the callback is registered. See sl_wifi_event_group_t for possible values. | 
| sl_wifi_callback_function_t | [in] | function | Function pointer to callback of type sl_wifi_callback_function_t that would be invoked when an event in the specified group occurs. | 
| void * | [in] | optional_arg | Optional user provided argument to pass additional context or information to the callback function. This would be passed back to callback handler of type sl_wifi_callback_function_t. | 
All the individual Wi-Fi events related to specific group would be triggered via this group callback.
This function allows the user to register a callback function for a specific group of Wi-Fi events sl_wifi_event_group_t. When any event within the specified group occurs, the registered callback function will be invoked, providing the event details and any associated data.
- Pre-conditions: - The Wi-Fi module must be initialized by calling sl_wifi_init before this API can be used. 
 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- Callbacks can be set only for event groups defined in sl_wifi_event_group_t, not for individual events defined in sl_wifi_event_t. 
sl_wifi_default_event_handler#
sl_status_t sl_wifi_default_event_handler (sl_wifi_event_t event, sl_wifi_buffer_t * buffer)
Default Wi-Fi event handler to be passed to sl_wifi_init.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_event_t | [in] | event | Wi-Fi event of type of sl_wifi_event_t. | 
| sl_wifi_buffer_t * | [in] | buffer | Buffer containing raw data from NWP firmware | 
This event handler would dispatch all the Wi-Fi events and invoke respective Wi-Fi group event.
This function serves as the default event handler for Wi-Fi events. When passed to the sl_wifi_init function, it would handle incoming Wi-Fi events by dispatching them to the appropriate group event functions.
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- Passing the event handler is optional. User can implement their own event dispatching handler if they prefer. 
sl_wifi_set_scan_callback#
static sl_status_t sl_wifi_set_scan_callback (sl_wifi_scan_callback_t function, void * optional_arg)
Register a callback for the SL_WIFI_SCAN_RESULT_EVENTS group event from sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_scan_callback_t | [in] | function | Callback function to register. This parameter specifies the callback function of type sl_wifi_scan_callback_t that would be invoked when an event in the SL_WIFI_SCAN_RESULT_EVENTS group occurs. | 
| void * | [in] | optional_arg | Optional user provided argument. This would be passed back to callback handler of type sl_wifi_scan_callback_t. | 
This function allows the user to register a callback function for the SL_WIFI_SCAN_RESULT_EVENTS group. When any event within this group occurs, the registered callback function would be invoked, providing the event details and any associated data.
- Pre-conditions: - sl_wifi_init should be called before this API. 
 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- All the individual Wi-Fi events related to this group would be triggered via this callback. 
sl_wifi_set_join_callback#
static sl_status_t sl_wifi_set_join_callback (sl_wifi_join_callback_t function, void * optional_arg)
Register a callback for SL_WIFI_JOIN_EVENTS group event from sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_join_callback_t | [in] | function | Function pointer to callback of type sl_wifi_join_callback_t. This parameter specifies the callback function that would be invoked when an event in the SL_WIFI_JOIN_EVENTS group occurs. | 
| void * | [in] | optional_arg | Optional user provided argument. This parameter allows the user to pass additional context or information to the callback function. This would be passed back to callback handler of type sl_wifi_twt_config_callback_t. | 
This function allows the user to register a callback function for the SL_WIFI_JOIN_EVENTS group. When any event within this group occurs, the registered callback function would be invoked, providing the event details and any associated data.
- Pre-conditions: sl_wifi_init should be called before this API. 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- All the individual Wi-Fi events related to this group will be triggered via this callback. 
sl_wifi_set_twt_config_callback#
static sl_status_t sl_wifi_set_twt_config_callback (sl_wifi_twt_config_callback_t function, void * optional_arg)
Register a callback for SL_WIFI_TWT_RESPONSE_EVENTS group event from sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_twt_config_callback_t | [in] | function | Function pointer to the callback of type sl_wifi_twt_config_callback_t. This parameter specifies the callback function that would be invoked when an event in the SL_WIFI_TWT_RESPONSE_EVENTS group occurs. | 
| void * | [in] | optional_arg | Optional user provided argument. This would be passed back to callback handler. | 
This function allows the user to register a callback function for the SL_WIFI_TWT_RESPONSE_EVENTS group. When any event within this group occurs, the registered callback function will be invoked, providing the event details and any associated data.
- Pre-conditions: sl_wifi_init should be called before this API. 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- All the individual Wi-Fi events related to this group would be triggered via this callback. 
sl_wifi_set_stats_callback#
static sl_status_t sl_wifi_set_stats_callback (sl_wifi_stats_callback_t function, void * optional_arg)
Register a callback for SL_WIFI_STATS_RESPONSE_EVENTS group event from sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_stats_callback_t | [in] | function | Function pointer to the callback of type sl_wifi_stats_callback_t. This parameter specifies the callback function that would be invoked when an event in the SL_WIFI_STATS_RESPONSE_EVENTS group occurs. | 
| void * | [in] | optional_arg | Optional user provided argument. This parameter allows the user to pass additional context or information to the callback function. This would be passed back to callback handler. | 
This function allows the user to register a callback function for the SL_WIFI_STATS_RESPONSE_EVENTS group. When any event within this group occurs, the registered callback function would be invoked, providing the event details and any associated data.
- Pre-conditions: sl_wifi_init should be called before this API. 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- All the individual Wi-Fi events related to this group would be triggered via this callback. 
sl_wifi_set_transceiver_callback#
static sl_status_t sl_wifi_set_transceiver_callback (sl_wifi_transceiver_callback_t function, void * optional_arg)
Register a callback for SL_WIFI_TRANSCEIVER_EVENTS group event of tye sl_wifi_event_group_t.
| Type | Direction | Argument Name | Description | 
|---|---|---|---|
| sl_wifi_transceiver_callback_t | [in] | function | Function pointer to the callback of type sl_wifi_transceiver_callback_t. This parameter specifies the callback function that would be invoked when an event in the SL_WIFI_TRANSCEIVER_EVENTS group occurs. | 
| void * | [in] | optional_arg | Optional user provided argument. This parameter allows the user to pass additional context or information to the callback function. This would be passed back to callback handler. | 
This function allows the user to register a callback function for the SL_WIFI_TRANSCEIVER_EVENTS group. When any event within this group occurs, the registered callback function would be invoked, providing the event details and any associated data.
- Pre-conditions: - sl_wifi_init should be called before this API. 
 
Returns
- sl_status_t. See Status Codes and Additional Status Codes for details. 
Note
- All the individual Wi-Fi events related to this group will be triggered via this callback.