|
|
udi_enumerate_ack(3udi)
Provide child instance information
#include <udi.h>void udi_enumerate_ack ( udi_enumerate_cb_t *cb, udi_ubit8_t enumeration_result, udi_index_t ops_idx ); /* Values for enumeration_result */#define UDI_ENUMERATE_OK 0 #define UDI_ENUMERATE_LEAF 1 #define UDI_ENUMERATE_DONE 2 #define UDI_ENUMERATE_RESCAN 3 #define UDI_ENUMERATE_REMOVED 4 #define UDI_ENUMERATE_REMOVED_SELF 5 #define UDI_ENUMERATE_RELEASED 6 #define UDI_ENUMERATE_FAILED 255ARGUMENTS cb is a pointer to an enumeration control block.
enumeration_result is a value indicating what type of enumeration acknowledgement is being generated.
ops_idx indicates (one of) the child binding ops index(es)-with associated metalanguage(s)-useable with this child device. If a driver calls udi_enumerate_ack multiple times with the same child_ID then each must have a different ops_idx, corresponding to a different meta_idx, and the environment may bind child drivers using any or all corresponding metalanguages. If enumeration_result is not UDI_ENUMERATE_OK, ops_idx is ignored and may be set to any value.
TARGET CHANNEL The affected driver instance's management channel.
DESCRIPTION The udi_enumerate_ack channel operation is used in response to a udi_enumerate_req channel operation and provides information about a particular child device instance.
The attr_list in the control block specifies the enumeration instance attributes that will be present for corresponding child driver instance(s) when created. These enumeration attributes may be obtained by a child driver via calls to udi_instance_attr_get, to obtain additional information about the instance being created. All child devices that match the filter_list in the enumeration request control block must be included in the set of enumeration acknowledgements. Other children may also be included.
The enumeration_result argument must be one of the following values and indicates the type of enumeration response being generated by the driver and how the associated child_ID and attr_list values in the control block should be interpreted:
UDI_ENUMERATE_OK - Indicates that the enumeration is returning a valid child instance enumeration and that no special cases apply. The attr_valid_length value is adjusted accordingly and the child_ID field is filled in by the driver with a value that uniquely identifies this child. This value will be used to identify the bind channel to that child in the udi_child_chan_context_t structure (if the udi_ops_init_t chan_context_size is non-zero).
UDI_ENUMERATE_LEAF - Indicates that there are not and never will be any child devices for the current device.
UDI_ENUMERATE_DONE - Indicates that all children have already been enumerated and no more child devices exist. This response does not actually enumerate a child.
UDI_ENUMERATE_RESCAN - Indicates that the Management Agent should re-scan the entire set of children via UDI_ENUMERATE_START and UDI_ENUMERATE_NEXT operations. This can be returned in situations where there are multiple changes to the set of child devices, where the set has changed part way through the enumeration process, or when the target driver is unable to determine the exact change that has occurred.
This response does not actually enumerate a child.
This value must only be returned for UDI_ENUMERATE_NEW and UDI_ENUMERATE_NEXT requests.UDI_ENUMERATE_REMOVED - Indicates that the specified child device has been removed (as opposed to added) and that the Management Agent should initiate handling of a device removal. The child_ID indicates which child has been removed by passing the same value that the child was originally enumerated with.
This value must only be returned for UDI_ENUMERATE_NEW requests.
It is important to note that the use of UDI_ENUMERATE_REMOVED for a UDI_ENUMERATE_NEW request is an explicit unenumeration of a child device. A child device may also be implicitly unenumerated by not listing it as part of a UDI_ENUMERATE_START / UDI_ENUMERATE_NEXT scan.
Whether explicitly or implicitly unenumerated, the driver must maintain the validity of the child_ID associated with this child until the Management Agent acknowledges the unenumeration with a udi_enumerate_req operation with an enumeration level of UDI_ENUMERATE_RELEASE.UDI_ENUMERATE_REMOVED_SELF - Treated like UDI_ENUMERATE_REMOVED, except that this indicates that the enumerating device itself has been removed.
UDI_ENUMERATE_RELEASED - The response from the driver when it has released all resources associated with a removed child device. This response must only be used with the UDI_ENUMERATE_RELEASE request and indicates that the driver has released all resources associated with the indicated child.
UDI_ENUMERATE_FAILED - Indicates that the dynamic or directed enumeration cannot be satisfied by this target driver. This may only be returned for UDI_ENUMERATE_NEW and UDI_ENUMERATE_DIRECTED requests.
In all cases except UDI_ENUMERATE_OK, the contents of attr_list is ignored and returned unchanged. The attr_valid_length member of the control block must always be zero except for the UDI_ENUMERATE_OK case, where it indicates the number of child enumeration attributes. In all cases except UDI_ENUMERATE_OK and UDI_ENUMERATE_REMOVED, the child_ID value is ignored.
warnings The control block must be the same control block as passed to the driver in the corresponding udi_enumerate_req operation.
REFERENCES udi_enumerate_req, udi_instance_attr_list_t, udi_enumerate_cb_t, udi_primary_init_t