openthread_sys

Type Alias otSrpClientCallback

Source 
pub type otSrpClientCallback = Option<unsafe extern "C" fn(aError: otError, aHostInfo: *const otSrpClientHostInfo, aServices: *const otSrpClientService, aRemovedServices: *const otSrpClientService, aContext: *mut c_void)>;
Expand description

Pointer type defines the callback used by SRP client to notify user of changes/events/errors.

This callback is invoked on a successful registration of an update (i.e., add/remove of host-info and/or some service(s)) with the SRP server, or if there is a failure or error (e.g., server rejects a update request or client times out waiting for response, etc).

In case of a successful reregistration of an update, aError parameter would be OT_ERROR_NONE and the host info and the full list of services is provided as input parameters to the callback. Note that host info and services each track its own state in the corresponding mState member variable of the related data structure (the state indicating whether the host-info/service is registered or removed or still being added/removed, etc).

The list of removed services is passed as its own linked-list aRemovedServices in the callback. Note that when the callback is invoked, the SRP client (OpenThread implementation) is done with the removed service instances listed in aRemovedServices and no longer tracks/stores them (i.e., if from the callback we call otSrpClientGetServices() the removed services will not be present in the returned list). Providing a separate list of removed services in the callback helps indicate to user which items are now removed and allow user to re-claim/reuse the instances.

If the server rejects an SRP update request, the DNS response code (RFC 2136) is mapped to the following errors:

  • (0) NOERROR Success (no error condition) -> OT_ERROR_NONE
  • (1) FORMERR Server unable to interpret due to format error -> OT_ERROR_PARSE
  • (2) SERVFAIL Server encountered an internal failure -> OT_ERROR_FAILED
  • (3) NXDOMAIN Name that ought to exist, does not exist -> OT_ERROR_NOT_FOUND
  • (4) NOTIMP Server does not support the query type (OpCode) -> OT_ERROR_NOT_IMPLEMENTED
  • (5) REFUSED Server refused for policy/security reasons -> OT_ERROR_SECURITY
  • (6) YXDOMAIN Some name that ought not to exist, does exist -> OT_ERROR_DUPLICATED
  • (7) YXRRSET Some RRset that ought not to exist, does exist -> OT_ERROR_DUPLICATED
  • (8) NXRRSET Some RRset that ought to exist, does not exist -> OT_ERROR_NOT_FOUND
  • (9) NOTAUTH Service is not authoritative for zone -> OT_ERROR_SECURITY
  • (10) NOTZONE A name is not in the zone -> OT_ERROR_PARSE
  • (20) BADNAME Bad name -> OT_ERROR_PARSE
  • (21) BADALG Bad algorithm -> OT_ERROR_SECURITY
  • (22) BADTRUN Bad truncation -> OT_ERROR_PARSE
  • Other response codes -> OT_ERROR_FAILED

The following errors are also possible:

  • OT_ERROR_RESPONSE_TIMEOUT : Timed out waiting for response from server (client would continue to retry).
  • OT_ERROR_INVALID_ARGS : The provided service structure is invalid (e.g., bad service name or otDnsTxtEntry).
  • OT_ERROR_NO_BUFS : Insufficient buffer to prepare or send the update message.

Note that in case of any failure, the client continues the operation, i.e. it prepares and (re)transmits the SRP update message to the server, after some wait interval. The retry wait interval starts from the minimum value and is increased by the growth factor every failure up to the max value (please see configuration parameter OPENTHREAD_CONFIG_SRP_CLIENT_MIN_RETRY_WAIT_INTERVAL and the related ones for more details).

@param[in] aError The error (see above). @param[in] aHostInfo A pointer to host info. @param[in] aServices The head of linked-list containing all services (excluding the ones removed). NULL if the list is empty. @param[in] aRemovedServices The head of linked-list containing all removed services. NULL if the list is empty. @param[in] aContext A pointer to an arbitrary context (provided when callback was registered).

Aliased Type§

enum otSrpClientCallback {
    None,
    Some(unsafe extern "C" fn(_: u32, _: *const otSrpClientHostInfo, _: *const otSrpClientService, _: *const otSrpClientService, _: *mut c_void)),
}

Variants§

§1.0.0

None

No value.

§1.0.0

Some(unsafe extern "C" fn(_: u32, _: *const otSrpClientHostInfo, _: *const otSrpClientService, _: *const otSrpClientService, _: *mut c_void))

Some value of type T.