INDConnector::Connect Method

Article
07/02/2010

Connects the endpoint to a listening peer.

Syntax

HRESULT Connect(
  [in]            INDEndpoint *pEndpoint,
  [in]            const struct sockaddr *pAddress,
  [in]            SIZE_T AddressLength,
  [in]            INT Protocol,
  [in, optional]  USHORT LocalPort,
  [in, optional]  const VOID *pPrivateData,
  [in]            SIZE_T PrivateDataLength,
  [in, out]       OVERLAPPED *pOverlapped
);

Parameters

pEndpoint [in]
An INDEndpoint interface that identifies the endpoint to use for the connection. The endpoint must have been created using this instance of the Connector object.
pAddress [in]
A sockaddr buffer that specifies the address of the peer to connect to. Typically, this is a sockaddr_in structure for IPv4 addresses and a sockaddr_in6 structure for IPv6 addresses.

The sin_port and sin6_port members are ignored for sockaddr_in and sockaddr_in6 address structures, respectively.
AddressLength [in]
Size, in bytes, of the pAddress buffer.
Protocol [in]
An IANA Internet Protocol number.
LocalPort [in, optional]
Local port number (in network byte order) to use. If zero, the provider will choose the port.
pPrivateData [in, optional]
Private data that is sent with the connection request. May be NULL if PrivateDataLength is zero.

To get this data, the peer calls the INDConnector::GetConnectionData method.
PrivateDataLength [in]
Length, in bytes, of the pPrivateData buffer. May be zero.
pOverlapped [in, out]
A pointer to an OVERLAPPED structure that is used to indicate completion of the operation.

Return Value

When you implement this method, you should return the following return values. If you return others, try to use well-known values to aid in debugging issues.

Return code	Description
ND_SUCCESS	The operation succeeded.
ND_PENDING	The request is pending and will be completed when the listening peer accepts the connection request.
ND_BUFFER_OVERFLOW	The specified private data length exceeded the capabilities of the underlying Network Direct hardware. The limits are reported in the ND_ADAPTER_INFO structure (see INDAdapter::Query).
ND_CANCELED	The endpoint was removed.
ND_DEVICE_REMOVED	The underlying Network Direct adapter was removed from the system.
ND_ CONNECTION_ACTIVE	This endpoint is already connected to another peer.
ND_HOST_UNREACHABLE	The destination address was not reachable.
ND_CONNECTION_REFUSED	The remote peer rejected the connection request.
ND_TIMEOUT	The connection request timed out. (Not returned directly by this method; returned only through INDOverlapped::GetOverlappedResult.) Timeout values are selected by Network Direct providers to match their respective network characteristics.
ND_ACCESS_VIOLATION	The pPrivateData buffer was not valid for the size specified in PrivateDataLength.
ND_INVALID_ADDRESS	The pAddress value is not valid.

Implementation Notes

Providers are responsible for transmitting the inbound and outbound read limits specified in the endpoint to the remote peer.

Remarks

The peer to which you are trying to connect must have issued a INDListen::GetConnectionRequest request to receive your connection request.

The connection is performed asynchronously. If the connection fails, the endpoint is not affected and remains in the same state as when the call was made.

When the request completes, you must call the INDConnector::CompleteConnect method to complete the connection process or the INDConnector::Reject method to reject the connection.

The protocol defines the content and format of the private data exchange. Typically, the private data contains information for negotiating the connection with the peer.

To abort a connection, you can release the endpoint or call the INDOverlapped::CancelOverlappedRequests method. The peer aborts the connection by rejecting the request.

Either side of a connection can terminate the connection by calling the INDConnector::Disconnect method. When an endpoint is disconnected, all requests are flushed. The completion status is ND_CANCELED for all outstanding Send and Receive requests on both sides of the connection.

Requirements

Product	Microsoft Message Passing Interface (MS-MPI)
Header	Ndspi.h