NTSTATUS
TdiDispatchCreate (
IN PDEVICE_OBJECT DeviceObject,
IN PIRP Irp
);
TdiDispatchCreate opens a file object that represents an address, connection endpoint, or control channel, setting up driver-allocated state to track subsequent I/O operations on the open file object.
A transport calls IoGetCurrentIrpStackLocation with the given Irp to get a pointer to its own stack location in the IRP, shown in the following list as IrpSp. The transport can use the information set in the following members of the IRP in processing a create request:
For an address, the EaName member is set to the system-defined constant TdiTransportAddress and the EA value following the EaName array is of type TRANSPORT_ADDRESS, set up by the client to specify the address to be opened. For some transports, this value can be a symbolic netBIOS or DNS name to be translated by the transport.
For a connection endpoint, the EaName member is set to the system-defined constant TdiConnectionContext and the EA value following the EaName array is a client-supplied handle, opaque to the transport driver. The transport must save this handle and subsequently pass it back to the client's registered event handlers for this connection.
If the given file object represents a control channel, this member is NULL.
TdiDispatchCreate returns STATUS_SUCCESS if the create/open operation succeeds and the transport has set up whatever state it uses to track subsequent I/O operations for the address, connection endpoint, or control channel. Otherwise, it can return any driver-determined status, such as one of the following:
Opening an address, connection endpoint, or control channel object is an inherently synchronous operation. TdiDispatchCreate can block waiting for internal driver functions to handle particular subtasks, such as initializing structures in driver-allocated context area(s) or checking the ACL for an address. However, TdiDispatchCreate should either set IoStatus.Status in the IRP to STATUS_SUCCESS or to an appropriate error status before it returns control.
A transport driver should fail any create/open request in which the buffer at Irp->AssociatedIrp.SystemBuffer contains EaName members set with TransportAddress and ConnectionContext. Clients must make separate calls to ZwCreateFile to open an address and a connection endpoint because a single file object cannot represent a combined address and connection endpoint.
A client opens a file object representing an address to indicate its transport address to the TDI driver. The first client to open such a file object can specify that it be either exclusive or shared. If the initial client specifies an exclusively opened file object, the transport driver fails all subsequent requests to open that address. If the initial client specifies a shared file object, the transport driver also fails all subsequent client requests for an exclusive open of that address. Otherwise, any number of clients can open the same file object for shared access of the same address.
Depending on the tranport, a client can specify a transport address to be opened or allow the transport driver to select an address. For example, a client might specify a TDI driver's broadcast address to receive datagrams in connectionless mode.
Opening a connection endpoint defines a client's end of a network connection. When TdiDispatchCreate processes such a request, it sets up the connection endpoint in an idle state. The client must eventually associate the open connection endpoint with an opened file object representing an address. That is, a transport does no I/O on an opened connection endpoint until it has been associated with an open address.
Opening a control channel sets up a control channel between a client and the TDI transport driver. A client can use an open control channel to query and set information not specifically tied to an address or connection endpoint. For example, a client might use an opened control channel to query the transport driver's broadcast address (used to receive broadcast datagrams) or to query performance statistics maintained in the transport.
By default, TdiDispatchCreate runs at IRQL PASSIVE_LEVEL.
TdiDispatchCleanup, TdiDispatchDeviceControl, TdiDispatchInternalDeviceControl, TRANSPORT_ADDRESS