14.2.2.6 Requests and confirmations

A function that performs an asynchronous request to a stack component commonly has a name ended with Req. The function argument in this case is a pointer to a structure which name is obtained from the function's name by adding _t, a mark denoting a type. This structure is regarded to in documentation as request parameters. The main field it includes is a pointer to a callback function which is called to confirm request execution. In addition to the callback function, request parameters include confirmation parameters structure as a field. The latter structure's name is obtained by replacing Req in its name to Conf. For example, network start request is issued by the ZDO_StartNetworkReq(ZDO_StartNetworkReq_t *req) function, where ZDO_StartNetworkReq_t has the confirm field of the ZDO_StartNetworkConf_t type.

An instance of request parameters must be declared as a global variable, because the confirmation callback's argument points exactly to the confirmation parameters' field inside the request parameters. This requires that the instance of request parameres exists after the invoking function loses control. Moreover, the user should ensure that the instance will not be reused while current request is being executed.

The status field of the confirmation parameters indicates whether the request is executed successfully and reports the failure reason if it is not a success. The status is given by the value of the enumeration type defined for each stack component (for example, APS_Status_t). However, the value of the status field may not fall in the range defined by the enumeration because a failure during request execution may occur not only on the layer to which the request is sent directly, but on the lower layers also.