3.6 Requests and Confirmations

In general, a function that performs an asynchronous request to a stack component has a name ending with Req. The argument for such a function is a pointer to a structure, the name of which comes from adding _t to the function’s name, indicating a type. This reference manual refers to this structure as request parameters. Its primary field is a pointer to a callback function, which the system invokes to confirm the execution of the request. Besides the callback function, the request parameters include a structure for confirmation parameters as a field. To derive the name of this structure, the user can replace Req with Conf in the original function’s name. For example, the ZDO_StartNetworkReq function issues a network start request with ZDO_StartNetworkReq (ZDO_StartNetworkReq_t *req), where ZDO_StartNetworkReq_t contains a confirm field of the ZDO_StartNetworkConf_t type.

The user must declare an instance of the request parameters as a global variable because the confirmation callback’s argument specifically references the confirmation parameter’s field within the request parameters. This requires that the instance of request parameters exists after the invoking function loses control. In addition, the user must avoid reusing the instance while the current request remains in execution.

The status field within the confirmation parameters indicates the success or failure of the request execution and, in the case of failure, provides the reason. The system assigns the status from the values of an enumeration type defined for each stack component, such as APS_Status_t. However, the value of the status field can exceed the range defined by the enumeration, as failures can occur not only at the target layer but also at lower layers during request execution.