|
|
udi_origin_t(3udi)
Request origination handle
#include <udi.h>typedef <HANDLE> udi_origin_t; /* NULL origin handle constant */#define UDI_NULL_ORIGIN <NULL_HANDLE>Description Environments may use the origin handle to maintain information about the origination of a user request. Each driver is responsible for copying the origin handle from received control blocks into any control blocks generated on behalf of that received control block. This origin handle may be used by the environment to maintain tracking, quota, or other information for the original request from its point of origin. The origin handle is an opaque handle.
The driver may set the UDI_NULL_ORIGIN value for a control block's origin field instead of copying an origin handle from another control block, but the driver cannot not create or allocate origin handles itself.
Origin handles are transferable between regions.
Warnings Drivers must not compare handle values for equality, but the UDI_HANDLE_IS_NULL macro can be used to determine if a handle variable currently holds a null value.
references UDI_HANDLE_IS_NULL, udi_cb_t
9.6.2 Self-Contained Opaque Types
A self-contained opaque type holds data that can be interpreted only by the environment. Unlike opaque handles, these types have "value" semantics rather than "reference" semantics. That is, assignment makes a copy of the entire object. If a self-contained opaque value is assigned to two different variables and one is modified (via an environment routine), the other will retain the original value.
This means that allocation calls are not needed for self-contained opaque types; drivers simply declare variables of this type and assign values to them.
Self-contained opaque types are not transferable between regions.
9.6.2.1 Timestamp Type
The timestamp type refers to a point in time, relative to an arbitrary starting point, in implementation-specific units. The timestamp type has the following type definition:
typedef <OPAQUE> udi_timestamp_t;As with abstract types, the size of the udi_timestamp_t type is expected to vary according to the needs of different environments.
Detailed usage of this type is described under udi_time_current.
9.7 Semi-Opaque Types
UDI defines semi-opaque types for objects that have driver-visible fields, but also have implementation-specific contents that are not visible to drivers. The driver-visible part of a semi-opaque object is defined as a C structure; drivers refer to the object using a pointer to this structure.
Semi-opaque objects must only be allocated by the environment, since the driver doesn't know how big the whole object is. This is typically done by calling an environment-provided service call such as udi_cb_alloc to allocate the object.
9.7.1 Control Blocks
UDI defines a control block type to provide context for asynchronous service calls and channel operations. UDI control blocks are semi-opaque objects and are transferable between regions.
See Chapter 11, "Control Block Management" for more details on control blocks.
9.7.1.1 Buffers
UDI defines a buffer type, which contains a variable-length collection of application or protocol data. UDI buffer data consists of a byte string that is logically contiguous, but which may be both physically and virtually segmented. In many cases, the actual storage will be of one or more structure types in the embedding system. UDI hides these machine- and OS-dependencies within the buffer object.
UDI buffers are semi-opaque objects and are transferable between regions.
See Chapter 13, "Buffer Management" for more details on UDI buffers.