Using reTurn Client APIs

From reSIProcate

Contents 1 Client API 1.1 Current Asynchronous Implementation 1.2 API Set 1.3 Asynchronous Callbacks

[edit] Client API

[edit] Current Asynchronous Implementation

• Application must provide an asio::io_service object and is responsible for threading it out and calling run
• Async Turn sockets must be held in a shared pointer, in order to ensure safety of asio callbacks - this could be abstracted better
• When Async sockets are created a callback handler class is passed in to receive callback notifications when operations are complete

[edit] API Set

• Synchronous API: Depending on the transport you want to use to reach the STUN/TURN server you first need to create the appropriate TurnSocket -> TurnUdpSocket, TurnTcpSocket, TurnTlsSocket
• Asynchronous API: Depending on the transport you want to use to reach the STUN/TURN server you first need to create the appropriate TurnAsyncSocket -> TurnAsyncUdpSocket, TurnAsyncTcpSocket, TurnAsyncTlsSocket
• Available client functions are:
  • setUsernameAndPassword()
  • requestSharedSecret() - username and password are returned
  • createAllocation(lifetime, bandwidth, requestedProps, reservationToken, requestedTransportType)
  • refreshAllocation(lifetime)
  • destroyAllocation()
  • getRelayTuple() - (SYNC API ONLY) used to retrieve info about the allocation
  • getReflexiveTuple() - (SYNC API ONLY) used to retrieve info about the allocation
  • getLifetime() - (SYNC API ONLY) used to retrieve info about the allocation
  • getBandwidth() - (SYNC API ONLY) used to retrieve info about the allocation
  • setActiveDestination(destinationIP, destinationPort) - sets the location where relayed packets should be sent
  • clearActiveDestination()
  • bindRequest()
  • send(bufferToSend, bufferSize);
  • sendTo(destinationIP, destinationPort, bufferToSend, bufferSize)
  • receive(bufferToReceiveIn, bufferSize[in/out], senderIPAddress, senderPort)
    • last 2 args are return args - if receive is non-blocking then this data is returned in callback instead
  • receiveFrom(bufferToReceiveIn, bufferSize[in/out], senderIPAddress, senderPort)
    • in this case last 2 args are input and specify endpoint we want to receive from

NOTE:  there is currently no support to do RFC3489 NAT type discovery

[edit] Asynchronous Callbacks

• onConnectSuccess(unsigned int socketDesc, const asio::ip::address& address, unsigned short port) = 0;
• onConnectFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
• onSharedSecretSuccess(unsigned int socketDesc, const char* username, unsigned int usernameSize, const char* password, unsigned int passwordSize) = 0;
• onSharedSecretFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
• onBindSuccess(unsigned int socketDesc, const StunTuple& reflexiveTuple) = 0;
• onBindFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
• onAllocationSuccess(unsigned int socketDesc, const StunTuple& reflexiveTuple, const StunTuple& relayTuple, unsigned int lifetime, unsigned int bandwidth, UInt64& reservationToken) = 0;
• onAllocationFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
• onRefreshSuccess(unsigned int socketDesc, unsigned int lifetime) = 0;
• onRefreshFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
• onSetActiveDestinationSuccess(unsigned int socketDesc) = 0;
• onSetActiveDestinationFailure(unsigned int socketDesc, const asio::error_code &e) = 0;
• onClearActiveDestinationSuccess(unsigned int socketDesc) = 0;
• onClearActiveDestinationFailure(unsigned int socketDesc, const asio::error_code &e) = 0;
• onReceiveSuccess(unsigned int socketDesc, const asio::ip::address& address, unsigned short port, const char* buffer, unsigned int size) = 0;
• onReceiveFailure(unsigned int socketDesc, const asio::error_code& e) = 0;
• onSendSuccess(unsigned int socketDesc) = 0;
• onSendFailure(unsigned int socketDesc, const asio::error_code& e) = 0;