Using reTurn Client APIs

From reSIProcate
Jump to: navigation, search

Client API[edit]

Current Asynchronous Implementation[edit]

  • 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

API Set[edit]

  • 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

Asynchronous Callbacks[edit]

  • 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;