Connection management API

[connor21]

Extending the libTML connection management requires new API functions.

Goals of the new API

• store connection to be reused in calls
• check connection properties
• allow closing connections
• allow validating connections
• events for connect/disconnect handling
• manage connections

manage connections

TML_CONNECTION_HANDLE

new object to refer to connections

tml_Core_Connect

Create a new connection.

coreHandle - TML core handle
sAddress - network address
connectionHandle - reference to a new connection handle

TML_INT32 tml_Core_Connect(TML_CORE_HANDLE coreHandle, const TML_CTSTR* sAddress, TML_CONNECTION_HANDLE* connectionHandle)

tml_Connection_Close

Close a connection and release resources.

connectionHandle - reference to TML connection handle

TML_INT32 tml_Connection_Close(TML_CONNECTION_HANDLE* connectionHandle)

tml_Connection_Get_Address

Returns the network address of remote peer.

connectionHandle - TML connection handle
sAddress - borrowed reference to network address

TML_INT32 tml_Connection_Get_Address(TML_CONNECTION_HANDLE connectionHandle, TML_CTSTR** sAddress)

tml_Connection_Get_RemoteProfiles

Returns the remote peer supported profiles.

connectionHandle - TML connection handle
lProfiles - reference to profile identification list. The list has to be released with sidex_Variant_DecRef().

TML_INT32 tml_Connection_Get_RemoteProfiles(TML_CONNECTION_HANDLE connectionHandle, SIDEX_VARIANT* lProfiles)

tml_Connection_Validate

Validate a connection.

connectionHandle - TML connection handle
bReconnect - TML_TRUE = try to reconnect if disconnected / TML_FALSE = don't try to reconnect
bConnected - TML_TRUE = connection is valid and connected, TML_FALSE = connection is closed

TML_INT32 tml_Connection_Validate(TML_CONNECTION_HANDLE connectionHandle, TML_BOOL breconnect, TML_BOOL* bConnected)

tml_Core_Get_ConnectionCount

Retruns the number of connections.

coreHandle - TML core handle
iCount - reference to the number of connections

TML_INT32 tml_Core_Get_ConnectionCount(TML_CORE_HANDLE coreHandle, TML_UINT32* iCount)

tml_Core_Get_Connection

Get connection handle from a TML core.

coreHandle - TML core handle
index - index of connection
connectionHandle - reference to the connection handle

TML_INT32 tml_Core_Get_Connection(TML_CORE_HANDLE coreHandle, TML_INT32 index, TML_CONNECTION_HANDLE* connectionHandle)

tml_Connection_SendAsync

Send async command on existing connection.

connectionHandle - TML connection handle
sProfile - profile identification string
cmdHandle - TML command handle
iTimeout - timeout in milliseconds

TML_INT32 tml_Connection_SendAsync(TML_CONNECTION_HANDLE connectionHandle, const TML_CTSTR* sProfile, TML_COMMAND_HANDLE cmdHandle, TML_UINT32 iTimeout)

tml_Connection_SendSync

Send sync command on existing connection.

connectionHandle - TML connection handle
sProfile - profile identification string
cmdHandle - TML command handle
iTimeout - timeout in milliseconds

TML_INT32 tml_Connection_SendSync(TML_CONNECTION_HANDLE connectionHandle, const TML_CTSTR* sProfile, TML_COMMAND_HANDLE cmdHandle, TML_UINT32 iTimeout)

tml_Cmd_Get_Connection

Get the connection on which the command was previously sent/received.

cmdHandle - TML command handle
connectionHandle - reference to connection handle

TML_INT32 tml_Cmd_Get_Connection(TML_COMMAND_HANDLE cmdHandle, TML_CONNECTION_HANDLE* connectionHandle)

tml_Core_Set_OnConnect

Set callback function to signal a new connection

coreHandle - TML core handle
pCBFunc - callback function or NULL to remove previously registered function
pCBData - custom data

TML_INT32 tml_Core_Set_OnConnect(TML_CORE_HANDLE coreHandle, TML_ON_CONNECT_CB_FUNC pCBFunc, TML_POINTER pCBData)

tml_Core_Set_OnDisconnect

Set callback function to signal a disconnection.

coreHandle - TML core handle
pCBFunc - callback function or NULL to remove previously registered function
pCBData - custom data

TML_INT32 tml_Core_Set_OnDisconnect(TML_CORE_HANDLE coreHandle, TML_ON_DISCONNECT_CB_FUNC pCBFunc, TML_POINTER pCBData)

TML_ON_CONNECT_CB_FUNC

Callback function to signal a new connection.

connectionHandle - TML connection handle
pCBData - custom data

typedef void(* TML_ON_CONNECT_CB_FUNC)(TML_CONNECTION_HANDLE connectionHandle, TML_POINTER pCBData)

TML_ON_DISCONNECT_CB_FUNC

Callback function to signal a closed connection.

connectionHandle - TML connection handle
pCBData - custom data

typedef void(* TML_ON_DISCONNECT_CB_FUNC)(TML_CONNECTION_HANDLE connectionHandle, TML_POINTER pCBData)