When a kernel-mode client makes a TDI_ASSOCIATE_ADDRESS request, it asks the underlying TDI transport driver to make an association between a particular open local-node address and an open connection endpoint.
IRP
The transport calls IoGetCurrentIrpStackLocation with the given Irp to get a pointer to its own I/O stack location in the IRP, shown in the following list as IrpSp. IRP members relevant to this request include the following:
IoStatus.Status
Specifies the final status of the associate-address request. The transport sets this member before it completes the IRP, possibly to one of the following:
STATUS_SUCCESS
STATUS_CONNECTION_ESTABLISHED
STATUS_INVALID_CONNECTION
STATUS_INVALID_HANDLE
The IoStatus.Information member is zero since this request transfers no data.
IrpSp->MajorFunction
Specifies IRP_MJ_INTERNAL_DEVICE_CONTROL. The transport can ignore this member if it exports a TdiDispatchInternalDeviceControl routine that handles only TDI_XXX requests.
IrpSp->MinorFunction
Specifies TDI_ASSOCIATE_ADDRESS.
IrpSp->FileObject
Points to an open file object representing the connection endpoint to be associated with the address specified at IrpSp->Parameters. The transport uses the FsContext and, possibly, FsContext2 fields to access the state it maintains about the connection.
IrpSp->Parameters
Points to a TDI_REQUEST_KERNEL_ASSOCIATE structure, defined as follows:
struct _TDI_REQUEST_KERNEL_ASSOCIATE {
HANDLE AddressHandle;
} TDI_REQUEST_KERNEL_ASSOCIATE, *PTDI_REQUEST_KERNEL_ASSOCIATE;
The transport uses the member of this structure as follows:
AddressHandle
Specifies a client-supplied handle to the file object representing the address.
The transport can call ObReferenceObjectByHandle to convert this handle into a pointer to the file object, which produces a reference to the file object representing the local-node address to be associated with the connection endpoint. The transport uses the FsContext and, possibly, FsContext2 fields of this file object to access the state it maintains about this address.
Comments
A kernel-mode client must make an associate-address request before it makes an endpoint-to-endpoint connection to the remote node either with a TDI_LISTEN request, optionally followed by a TDI_ACCEPT request, to the transport driver or with a TDI_CONNECT request to the transport driver. The client can get or set information about the connection with TDI_QUERY_INFORMATION or TDI_SET_INFORMATION requests before making an associate-address request.
After the connection endpoint has been associated with the address, the client can make any other TDI_XXX requests to the transport on the connection with one exception: it cannot make a TDI_ASSOCIATE_ADDRESS request again for the specific endpoint until it makes a successful TDI_DISASSOCIATE_ADDRESS request to the transport.
For example, a client might register one or more ClientEvent(Chained)Receive(Expedited) handlers on the address by submitting one or more TDI_SET_EVENT_HANDLER requests if its subsequent TDI_LISTEN request will be satisfied as soon as a remote-node peer offers a connection. On the other hand, a client that sets up a listen for a delayed-connection acceptance might defer registering receive-event handler(s) until just before it submits a TDI_ACCEPT for an offered connection.
TdiBuildAssociateAddress is the macro a client uses to fill in this IRP.
See Also
ClientEventChainedReceive, ClientEventChainedReceiveExpedited, ClientEventReceive, ClientEventReceiveExpedited, TDI_ACCEPT, TdiBuildAssociateAddress, TDI_CONNECT, TDI_DISASSOCIATE_ADDRESS, TdiDispatchInternalDeviceControl, TDI_LISTEN, TDI_QUERY_INFORMATION, TDI_SET_EVENT_HANDLER, TDI_SET_INFORMATION