TDI_STATUS
TdiDispatchCreate (
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
);
TdiDispatchCreate calls a TDI driver routine that opens an address, connection endpoint, or control channel object.
Note If opening an address, connection endpoint, or control channel object is a synchronous operation, its timing depends on the TDI driver.
Parameters
DeviceObject
Points to the device object that describes the TDI driver.
Irp
Points to the IRP the Windows NT kernel passes to TdiDispatchCreate. The IRP major function code is IRP_MJ_CREATE.
Return Value
TdiDispatchCreate can return the following status codes:
STATUS_DUPLICATE_NAME
STATUS_INSUFFICIENT_RESOURCES
STATUS_NONEXISTENT_EA_ENTRY
STATUS_PENDING
STATUS_SUCCESS
For more information about status codes, see Part II, Chapter 10.
Comments
IRP fields related to an open object request are:
| IRP Component | Meaning |
| IoStatus.Status | Specifies the final status of the open object request. |
| IrpSp->MajorFunction | Specifies IRP_MJ_CREATE. |
| IrpSp->MinorFunction | Unused. |
| IrpSp->FileObject | Points to a file object the I/O subsystem creates to represent the address, connection endpoint, or control channel object. The TDI driver fills in FsContext and FsContext2 with pointers to driver data structures that represent it. |
| Irp->AssociatedIrp.SystemBuffer | For an address object, points to a FILE_FULL_EA_INFORMATION structure. The TDI client uses this structure to specify a TRANSPORT_ADDRESS structure containing the address for the object. The EA name for the address object is “TransportAddress” (the TDI constant TdiTransportAddress contains this value). |
| For a connection endpoint object, points to a FILE_FULL_EA_INFORMATION structure. The TDI client uses this structure to specify the connection context. The EA name for the context is “ConnectionContext” (the TDI constant TdiConnectionContext contains this value). | |
| For a control channel object, specifies NULL. | |
| IrpSp->Parameters.Create.EaLength | For an address or connection endpoint object, specifies the length, in bytes, of the buffer specifying the transport address or connection context, respectively. For a control channel object, specifies 0. |
| IrpSp->Parameters.Create. ShareAccess |
For an address object, specifies shared access if the I/O subsystem has set either the FILE_SHARE_READ or the FILE_SHARE_WRITE bit. Otherwise, specifies an exclusive address object open. Unused for the other two types of file objects. |
| IrpSp->Parameters.Create. SecurityContext->AccessState |
For an address object, defines the associated ACL. The first client to open the object sets the ACL, and the TDI driver checks subsequent open address object requests against it. Currently unused for the other two types of file objects. |
Note It is illegal for the client to specify both a TransportAddress EA and a ConnectionContext EA in the same CreateFile call for an address or connection endpoint object.
A client opens an address object to indicate its transport address to the TDI driver. Several clients can share an address object. The client opening the object can specify it to be either shared or exclusive. If the client specifies a shared object, subsequent client requests for an exclusive open will fail. Similarly, if the original client specifies an exclusively opened object, all subsequent requests for that object will fail.
The client can specify a transport address for the TDI driver to associate with the object, or it can allow the driver to select the address. If the client wants to receive datagrams in connectionless mode, it can specify the TDI driver broadcast address for the object.
The TDI client opens a connection endpoint object to define its end of a network connection. When the TDI driver receives the client request, it sets up a connection endpoint object in an idle state. The client must eventually associate this object with an address object.
The client specifies a connection context when opening a connection endpoint object. This context is an unsigned 32-bit value that the TDI driver does not interpret. The driver merely passes the context back to the client when required in calls to client event handlers.
Opening a control channel object sets up a control channel between the client and the TDI driver. The client uses this channel to query and set information not specifically tied to an address or connection endpoint object. For example, the client can use the control channel to query the TDI driver broadcast address (used to receive broadcast datagrams).