|
|
udi_cb_alloc(3udi)
Allocate a new control block
#include <udi.h>void udi_cb_alloc ( udi_cb_alloc_call_t *callback, udi_cb_t *gcb, udi_index_t cb_idx, udi_channel_t default_channel ); typedef void udi_cb_alloc_call_t ( udi_cb_t *gcb, udi_cb_t *new_cb );ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
cb_idx is a control block index that indicates required properties of the control block, such as metalanguage type and scratch size.
default_channel is a channel handle that, if set to a value other than UDI_NULL_CHANNEL, is used as the initial value for the new control block's channel member. If set to UDI_NULL_CHANNEL, the environment is free to initialize the channel member with some other value, so the driver must not depend on it containing UDI_NULL_CHANNEL.
new_cb is a pointer to the newly allocated control block.
DESCRIPTION udi_cb_alloc allocates a new control block for use by the driver. The new control block can be used to allocate other resources using any UDI service request or to invoke channel operations appropriate to the specified control block type.
While such allocations are usually performed using a specific control block already associated with a channel operation, the new control block returned by udi_cb_alloc provides a way to continue or complete the channel operation without waiting for a service call to complete. This is particularly useful when initiating delayed callbacks with udi_timer_start or udi_timer_start_repeating.
When a new control block is allocated, its context member is initialized to the context value from gcb, its origin member is initialized to the origin value from gcb, its channel member is initialized according to the default_channel argument block passed to udi_cb_alloc, and its initiator_context value is unspecified.
The scratch pointer of the new control block is initialized to point to the associated scratch area and the pointer must not be modified by the driver. If the driver's scratch requirement is zero, the value of the scratch pointer is unspecified and it must not be dereferenced.
The initial values in the new control block's scratch space are unspecified; they are not guaranteed to be zero. Similarly, for metalanguage-specific control blocks that have additional visible structure members, the initial value of these structure members are also unspecified.
WARNINGS The control block obtained with this call must not be used with metalanguage-related channel operations other than those appropriate for the control block type associated with cb_idx. If the control block index was associated with a udi_gcb_init_t in udi_init_info, rather than a metalanguage-specific udi_cb_init_t, then the new control block must not be used with any channel operations.
The driver must not explicitly set the channel member of the returned control block to UDI_NULL_CHANNEL at any time and must not expect UDI_HANDLE_IS_NULL to return TRUE for the channel member of a control block even if default_channel was UDI_NULL_CHANNEL.
Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
REFERENCES udi_cb_t, udi_cb_free, udi_timer_start, udi_timer_start_repeating, udi_init_info, udi_cb_init_t