TdiBuildAssociateAddress

VOID
TdiBuildAssociateAddress (
IN PIRP Irp,
IN PDEVICE_OBJECT DevObj,
IN PFILE_OBJECT FileObj,
IN PVOID CompRoutine,
IN PVOID Contxt,
IN HANDLE AddrHandle
);

TdiBuildAssociateAddress sets up an internal device control IRP for a TDI_ASSOCIATE_ADDRESS request to the underlying transport in which a local-node client has already opened an address and a connection endpoint.

Parameters

Irp: Points to a client-supplied IRP, either originating in a higher level network component or allocated with TdiBuildInternalDeviceControlIrp.
DevObj: Points to the device object created by the next lower TDI transport driver.
FileObj: Points to a file object representing the connection endpoint.
CompRoutine: Specifies the entry point of a client-supplied IoCompletion routine or NULL. The I/O Manager calls this routine when the given IRP is completed, unless the client sets this parameter to NULL.
Contxt: Points to a client-determined context. This client-supplied pointer is passed in to the IoCompletion routine when it is called with the completed IRP. Contxt should be NULL if CompRoutine is NULL.
AddrHandle: Specifies a handle to a file object representing a local-node address.

Comments

TdiBuildAssociateAddress sets IRP_MJ_INTERNAL_DEVICE_CONTROL as the MajorFunction and TDI_ASSOCIATE_ADDRESS as the MinorFunction codes in the transport's I/O stack location of the given IRP.

A kernel-mode client must open both a connection endpoint and an address with successful calls to ZwCreateFile before it calls TdiBuildAssociateAddress. The client must make the associate-address request before it makes a connection to the remote node either with a request set up with TdiBuildListen, optionally followed by one set up with TdiBuildAccept, to the transport driver or with a request set up with TdiBuildConnect to the transport driver.

However, a client can get and/or set information about the open connection or address with one or more requests set up with TdiBuildQueryInformation and/or TdiBuildSetInformation before making the associate-address request.

After the client associates the connection endpoint with the address, it can make any other TDI_XXX requests to the transport on the just-associated 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.