gt2Connect

GameSpy SDK

gt2Connect

Initiates a connection between a local socket and a remote socket.

GT2Result gt2Connect(
GT2Socket socket,
GT2Connection * connection,
const char * remoteAddress,
const GT2Byte * message,
int len,
int timeout,
GT2ConnectionCallbacks * callbacks,
GT2Bool blocking );
RoutineRequired HeaderDistribution
gt2Connect<gt2.h>SDKZIP

Return Value

If blocking is true, GT2Success means the connect attempt succeeded, and anything else means it failed.
If blocking is false, GT2Success means the connection is being attempted, and anything else means there was an error and the attempt has been abored.

Parameters

socket
[in] The handle to the socket.
connection
[out] A pointer to where the connection handle will be stored.
remoteAddress
[in] The address to connect to.
message
[in] An optional initial message (may be NULL).
len
[in] Length of the initial message (may be 0, or -1 for strlen)
timeout
[in] Timeout in milliseconds (may be 0 for infinite retries)
callbacks
[in] GT2Connection related callbacks.
blocking
[in] If GT2True, don't return until the attempt has completed (successfully or unsuccessfuly).

Remarks

The gt2Connect function is used to initiate a connection attempt to a remote socket on the Internet. After the remote socket is contacted, both it and the local connector will authenticate the other during a negotation phase. Once the remote socket accepts the connection attempt, the connection will be established. The connection lasts until the closed callback gets called, which can happen because one side closed the connection with gt2CloseConnection (or gt2CloseConnectionHard), there was some sort of error on the connection, or the socket either connection uses is closed.
This call returns GT2Success if there are no problems starting the connection attempt, otherwise the return values signals the reason for the failure. If this call is blocking (blocking set to GT2True), then the return value signals the result of the entire connection attempt: GT2Success means the attempt succeeded, any other value means it failed. If the result is GT2Sucess, then the gt2Connection variable pointed to by the connection parameter will be set to this connection’s gt2Connection object. If this call is blocking, and it fails, the gt2ConnectionCallbacks’s connected callback may or may not be called. If there is some sort of initial failure (such as an error resolving the remote address, or allocating memory for the connection), the callback will not be called. If it fails after starting the negotiation process, then the callback will be called. Note that the 7 byte header must be accounted for in the message since the connection message is sent reliably.