Configuration

bool DetectConnectivity(int serverStoreID, const struct AfFirewallDetectionParams *pFirewallDetectionParams);
Starts the detection and analysis of the system's local interfaces. It is used to complete the configuration of the AnyFirewall Engine by determining NAT types, the presence of UPnP enabled devices, HTTP proxies, and local and reflexive IP address(es) (more than one for multiple interfaces).
DetectConnectivity should be called after:
1. Initializing and configuring the AnyFirewall Engine.
2. Resetting the STUN, TURN, or proxy server settings.
3. Receiving an EAfEventNetworkInterfacesChanged event.
4. After setting IP address using SetInterfaceAddress(..).
In Microsoft® Lync™ mode, detection of NAT type and HTTP proxy is not done.


Parameters:

int serverStoreIDA unique server store id for individual server settings.
const struct AfFirewallDetectionParams *pFirewallDetectionParams This parameter can be used to customize the checks to be performed by this function.
struct AfFirewallDetectionParams
{
     int iDetectUdpConnectivity;
     int iDetectTcpConnectivity;
     int iDetectProxyConnectivity;
     int iDetectUPnPConnectivity;
     int iCheckTurnCredentials;
     int iUPnPDeviceDiscoveryTimeout;
};
The struct members iDetectUdpConnectivity, iDetectTcpConnectivity, iDetectProxyConnectivity, iDetectUPnPConnectivity specify whether to check for UDP, TCP, proxy and UPnP connectivity respectively. A non-zero value means true and zero means false. Similarly, the member iCheckTurnCredentials indicates whether to check the validity of TURN server credentials during this phase. The default value of these parameters is 1. Finally, iUPnPDeviceDiscoveryTimeout specifies the timeout in milliseconds for UPnP device discovery. The default is 3000 ms. If pFirewallDetectionParams is NULL, the default values will be used.

Return values:

boolShould return true. Returns false if the AnyFirewall™ Engine is not initialized.


bool SetNetworkType(const int serverStoreID, EAfNetworkType nType)
This API sets specific network type which will be used by AFE.This API can be used to set IPv4 only, IPv6 only or Dual-Stack network type. By default AFE operates in Dual-Stack mode.
DetectConnectivity() API must be invoked after invoking this API.


Parameters:

int serverStoreIDAn unique server store id for individual server settings.
EAfNetworkType nTypeNetwork Type(IPv4,IPv6 or Dual_Stack) AFE will use.


Return value:

boolReturns true if succeeded and false if fails.
Network Type values(enum EAfNetworkType):
    EAfDUAL,
    EAfIPv4Only,
    EAfIPv6Only


void SetInterfaceAddress(int serverStoreID, const std::string& sIPAddress);
This API sets specific interface address(es) which will be used by AFE as outbound interface(s). This API can be used to set IPv4 only, IPv6 only or dual-stack address(es). API will take interface address(es) in string format. Every interface address will end with a semi-colon(;) and there must not be any white-space. For example,
SetInterfaceAddress("192.168.0.176;");
SetInterfaceAddress("192.168.0.176;2001:470:19:473::c0a8:a18;");
SetInterfaceAddress("192.168.0.176;2001:470:19:473::c0a8:a18;192.168.2.176;");
If no valid interface address is passed by this API, AFE will work with detected interface address(es) from system.
DetectConnectivity() API must be invoked after invoking this API.


Parameters:

int serverStoreIDA unique server store id for individual server settings.
const std::string& sIPAddressA string with one or more interface address, every address must end with a semi-colon.


int WaitForDetectConnectivity(int serverStoreID, int iTimeoutMillisec);
Wait a period of time for DetectConnectivity to complete. This can be used to ensure connectivity is analyzed before calling the following functions: Connect, MakeOffer, or MakeAnswer.


Parameters:

int serverStoreIDA unique server store id for individual server settings.
int iTimeoutMillisecThe amount of time in milliseconds to wait for DetectConnectivity to complete.

Return value:

int0 is returned on success and 1 on timeout.
void SetRealm(int serverStoreID, const std::string& sRealm);
Sets the realm for long-term credentials for the Eyeball AnyFirewall™ Server which will be included in the allocation request. If the API is not called it will take NULL string as realm in the allocation request


Parameters:

int serverStoreIDA unique server store id for individual server settings.
const std::string& sRealmThe realm used on the AnyFirewall™ Server.
std::string GetRealm(int serverStoreID);
Returns the realm used on the AnyFirewall™ Server as part of long-term credentials.

Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

boolShould return true. Returns false if the AnyFirewall™ Engine is not initialized.
bool SetTURNUsernamePassword(int serverStoreID, const std::string& sUsername, const std::string& sPassword);
Sets the long-term credentials for the Eyeball AnyFirewall™ Server. The AnyFirewall™ Engine can connect to any other STUN and TURN compliant server as well.


Parameters:

int serverStoreIDA unique server store id for individual server settings.
const std::string& sUsernameThe username used on the AnyFirewall™ Server.
const std::string& sPasswordThe password of the user.

Return value:

boolShould return true. Returns false if the AnyFirewall™ Engine is not initialized.
std::string GetTURNUsername(int serverStoreID);
Returns the username used on the Any-Firewall™ Server as part of long-term credentials.


Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe username used on the AnyFirewall™ Server.
std::string GetTURNPassword(int serverStoreID);
Returns the password used on the Any-Firewall™ Server as part of long-term credentials.


Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe password used on the AnyFirewall™ Server.


bool SetSTUNServer(int serverStoreID, const std::string& sHost);
Sets the IP address or hostname of the STUN Server of the Eyeball AnyFirewall™ Server. The AnyFirewall™ Engine can connect to any other STUN-compliant server as well. The AnyFirewall™ Engine will send binding requests to the STUN Server. The STUN server can be accessed using UDP and TCP. UDP is required to detect the firewall settings; TCP is used to check whether TCP connections can be made.
Example: "public 64.85.36.178 3478 udp; public 64.85.36.178 3478 tcp;".


Parameters:

int serverStoreIDA unique server store id for individual server settings.
const std::string& sHostThe host description of the STUN Server, created by CreateHost.

Return value:

boolShould return true. Returns false if the AnyFirewall™ Engine is not initialized.
std::string GetSTUNServer(int serverStoreID);
Returns the host description string of the STUN Server, e.g. “public 64.85.36.178 3478 udp;”. For details about host description strings please see 6.3. AFE: Host Types 


Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe description of the STUN Server.
bool SetTURNServer(int serverStoreID, const std::string& sHost);
Sets the IP address or hostname of the TURN Server of the Eyeball AnyFirewall™ Server. The AnyFirewall™ Engine can connect to any other TURN-compliant server as well. The AnyFirewall™ Engine will send TURN messages to the TURN Server. TURN can be used over UDP and TCP.
It is recommended to set both transport protocols to make full use of the relaying capabilities of AnyFirewall™ Engine.
Example: "public 64.85.36.178 443 udp; public 64.85.36.178 443 tcp;".


Parameters:

int serverStoreIDA unique server store id for individual server settings.
const std::string& sHostThe host description of the TURN Server, created by CreateHost.

Return value:

boolShould return true. Returns false if the AnyFirewall™ Engine is not initialized.


std::string GetTURNServer(int serverStoreID);
Returns the host description string of the TURN Server, e.g. "public 64.85.36.186 5070 udp; public 64.85.36.186 443 tcp;". For details about host description strings please see 6.3. AFE: Host Types.

Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe description of the TURN Server.


bool SetHTTPProxy(int serverStoreID, const std::string& sHost, const std::string& sUsername, const std::string& sPassword,const std::string& sDomain);
Sets the parameters to access an HTTP proxy. If not set, the AnyFirewall™ Engine detects the HTTP proxy using the HTTP proxy settings stored for Internet Explorer.

Parameters:

int serverStoreIDA unique server store id for individual server settings.
const std::string& sHostThe host description of the HTTP proxy, created by CreateHost. Example: "public proxy.eyeball.com 8080 tcp;"
const std::string& sUsernameThe username used on the HTTP proxy.
const std::string& sPasswordThe password of the user.
const std::string& sDomainThe HTTP proxy domain. Only required for NTLM authentication.

Return value:

boolShould return true. Returns false if the AnyFirewall™ Engine is not initialized.


std::string GetHTTPProxy(int serverStoreID);
Returns the host description string of the HTTP Proxy, e.g. “public proxy.eyeball.com 8080 tcp;”. For details about host description strings please see  6.3. AFE: Host Types.

Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe description of the HTTP proxy.


std::string GetHTTPProxyUsername(int serverStoreID);
Returns the username used on the HTTP Proxy.

Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe username used on the HTTP proxy.


std::string GetHTTPProxyPassword(int serverStoreID);
Returns the password used on the HTTP Proxy.

Parameters:

int serverStoreIDA unique server store id for individual server settings.

Return value:

std::stringThe password used on the HTTP proxy.


std::string GetHTTPProxyRealm();
Returns the realm used on the HTTP Proxy for NTLM authentication.

Return value:

std::stringThe realm used on the HTTP proxy.


unsigned long DNS_LookupIPv4Address(int iDnsChannel, const std::string& sHostName)
Resolves the hostname sHostName, and returns the IP address in network byte order.

Parameters:

int iDnsChannelThe ID of a DNS Channel
const std::string& sHostNameThe hostname

Return value:

unsigned longResolved IP in network byte order or 0 in case of error.c
std::string* DNS_LookupIPv4Addresses(const int serverStoreID, const std::string& sHostName, int& iNumResults)
Resolves the hostname sHostName, and returns only IPv4 addresses as an array of string. The number of IPv4 addresses is returned in the iNumResults parameter.

Parameters:

int serverStoreIDAn unique server store id for individual server settings.
const std::string& sHostNameThe hostname
int &iNumResultsReference parameter that holds the number of IPv4 addresses it discovered by resolving the hostname sHostName.

Return value:

std::string*Array of string that holds the resolved IPv4 addresses.


std::string* DNSLookupForIPv6Addresses(const int serverStoreID, const std::string& sHostName, int& iNumResults)
Resolves the hostname sHostName, and returns only IPv6 addresses as an array of string. The number of IPv6 addresses is returned in the iNumResults parameter.

Parameters:

int serverStoreIDAn unique server store id for individual server settings.
const std::string& sHostNameThe hostname
int &iNumResultsReference parameter that holds the number of IPv6 addresses it discovered by resolving the hostname sHostName.

Return value:

std::string*Array of string that holds the resolved IPv6 addresses.


std::string* GetIPAddressesFromDNS(const int serverStoreID, const std::string& sHostName, int& iNumResults)
Resolves the hostname sHostName, and returns both IPv4 and IPv6 addresses as an array of string. The number of IP addresses is returned in the iNumResults parameter.
int serverStoreIDAn unique server store id for individual server settings.
const std::string& sHostNameThe hostname
int &iNumResultsReference parameter that holds the number of IPv4 and IPv6 addresses it discovered by resolving the hostname sHostName.

Return value:

std::string*Array of string that holds the resolved IPv4 and IPv6 addresses.


std::string DNS_SRV_Lookup(int iDnsChannel, const std::string& sTarget, const std::string& sProtocol)
Performs DNS-SRV query and returns the discovered hosts as a list of hosts, delimited by semicolons. Each host is in the form of "<host-type><IP address><port><transport>". The different parts of the host descriptions and their meanings are described in detail in 6.3. AFE: Host Types.

Parameters:

int iDnsChannelThe ID of a DNS Channel
const std::string& sTargetThe DNS SRV entry e.g. "_sip._udp.eyeball.com"
const std::string& sProtocolThe protocol e.g. AF_PROTOCOL_TLS

Return value:

std::stringHost list of discovered hosts


bool SetPortRange(int iBottomRange, int iTopRange, const std::string& socketType)
This function can be used to specify a range of ports to be used by AFE. Whenever AFE needs to bind a port, it will try to use a port from this range.
This function affects all channels created.

In Microsoft® Lync™ mode, if a fixed TCP port is desired, the port number can be provided for both the bottom and the top range. If a fixed port is specified, only one media stream can be used in the session. According to MS-ICE2, multiplexing occurs with TCP candidates for RTP and RTCP components. Hence, one port is enough for TCP candidates of one media stream. If another media stream attempts to use the same port, it can gather host candidates, but fails to gather server reflexive and relayed candidates since allocation has already been made for that port for the first media stream.

In Microsoft® Lync™ mode, for a fixed TCP port specified by this function, with one media stream, the call should establish for both P2P and relay cases. For two media streams, the call should establish for only the P2P case as relayed candidates cannot be gathered for the second media stream.

Parameters:

int iBottomRangeThe lower limit of the port range.
int iTopRangeThe upper limit of the port range.
const std::string& socketTypeThis can be either AF_PROTOCOL_UDP or AF_PROTOCOL_TCP.

Return value:

boolThe function returns whether it succeeded (true) or failed (false).


bool SetMediaPortRange(int iBottomRange, int iTopRange, const std::string& socketType)
This function can be used to specify a range of ports to be used for media channels by AFE. Whenever AFE needs to bind a media port, it will try to use a port from this range. AFE will not use any port from this port range for its internal usage.
This function affects all channels created. If the port is not specified while creating a channel, AFE will bind any available port from the system even though media port range has been set. So, it is recommended to use specific port when the media port range is set.

Parameters:

int iBottomRangeThe lower limit of the port range.
int iTopRangeThe upper limit of the port range.
const std::string& socketTypeThis can be either AF_PROTOCOL_UDP or AF_PROTOCOL_TCP.

Return value:

boolThe function returns whether it succeeded (true) or failed (false).


bool SetBandwidthManagement(int serverStoreID, int bEnable);
This function is used to set bandwidth management globally. If global bandwidth management is true then we can enable or disable bandwidth management on specified channels. This is applicable only in answerer end. Don't enable this in Offerer end.

Note: This API is only applicable for Microsoft Lync mode. For others mode the API will return false.

Parameters:

int serverStoreIDA unique server store id for individual server settings.
int bEnable set 1 to set true,0 to set false.
The default value is false.

Return value:

boolThe function returns whether it succeeded (true) or failed (false).


int GetAllocatedBandwidth(int iChannel);
This API is used to get the allocated bandwidth for a specific channel.

Note: This API is only applicable for Microsoft Lync mode. For others mode the API will return -1.

Parameters:

int iChannelSpecifies the channel number

Return value:

intThe function returns the allocated bandwidth.


std::string GetReservationId(int iChannel);
This function returns the reservation ID of 16 bytes from the TURN server.

Note: This API is only applicable for Microsoft Lync mode. For others mode the API will return empty string.

Parameters:

int iChannelSpecifies the channel number

Return value:

std::stringReturns the reservation ID


void SetDefaultCandidatePreferenceOrder(enum CandidateType defaultCandidatePreferenceOrder[], int sizeOfPreferenceOrderList, bool forceReInviteDisabled)
Configures the order of preference for default candidate in offer or answer SDP.

Note: This API is only applicable for Microsoft Lync mode.

Once configured, the order remain in effect for every subsequent SDP. To change the order, use the function ResetDefaultCandidatePreferenceOrder().

If no preference order is set, the default preference order is:

  • For MS-ICE2 Regular mode: UDP host candidate, UDP server reflexive candidate, UDP relayed candidate, TCP relayed candidate, TCP server reflexive candidate.
  • For MS-ICE2 TCP-only mode: TCP host candidate, TCP relayed candidate, TCP server reflexive candidate.


This function is applicable only for Microsoft® Lync™ mode.
It is RECOMMENDED that the default candidate be chosen in the following order - relayed candidate, server reflexive candidate, host candidate (Ref: ICE Protocol).

Parameters:

enum CandidateType defaultCandidatePreferenceOrder[ ]List of values from enumeration CandidateType.
int sizeOfPreferenceOrderListNumber of CandidateType values present in the list
bool forceReInviteDisabledFalse if reINVITE is to be sent always, true otherwise


If SetDefaultCandidatePreferenceOrder function is not configured then reINVITE will always occur.


void ResetDefaultCandidatePreferenceOrder()
Resets the preference order if it was set by SetDefaultCandidatePreferenceOrder().
This function is applicable only for Microsoft® Lync™ mode.

Note: This API is only applicable for Microsoft Lync mode.

Default preference order will be enforced:

  • For MS-ICE2 Regular mode: UDP host candidate, UDP server reflexive candidate, UDP relayed candidate, TCP relayed candidate, TCP server reflexive candidate.
  • For MS-ICE2 TCP-only mode: TCP host candidate, TCP relayed candidate, TCP server reflexive candidate.


std::string GetLocalInterfaceIPs()
Returns interface IP address (es) of the system. If there is more than one interface IP address then the addresses will be space separated.

Return value:

std::stringThe function returns the local interface address (es).


void SetCertificate(const std::string& certificateFile, const std::string& privateKeyFile)
Sets the client certificate and private key (.pem) file. Note that, to set different certificate/private key for a channel, client's only have to call this API before creating a channel. Channels created previously using different certificate will have no impact on this.
This API must be called before creating MTLS channel.

Parameters:

const std::string& certificateFile String that contains the full path of the certificate file, e.g "C:\RootFolder\Folder2\certFile.pem" for Windows or "/rootFolder/Folder2/certFile.pem" for Unix.
const std::string& privateKeyFile String contains full path of private key file.


typedef int (*custom_cert_verify_callback)(void *x509_store_ctx, void *arg)
A function pointer type used by SetCertificateVerificationCallback API. Clients must define function that conform this function signature. When set by client, this function will be invoked by AFE to verify the peer certificate during TLS connection attempt.

Parameters:

void *x509_store_ctxClient will receive an instance of X509_STORE_CTX structure that is the certificate store of the other peer AFE attempting to connect. Using this certificate store client can verify the peer certificate.
void *argCurrently provides channel ID pointer.


Return value:

Client callback must return 1 when certificate is verified successfully. Otherwise client should return 0. Returning 1 will make AFE continue the TLS connection process. Returning 0 will cause AFE abort the TLS connection process.

void SetCertificateVerificationCallback(custom_cert_verify_callback callback)
The API to set the client callback that will be invoked to verify peer certificate during TLS connection process.

Parameters:

custom_cert_verify_callback callbackThe client callback function’s pointer.


Sample code:

static int custom_callback(void *ctx, void *arg)
{
      X509_STORE_CTX
      store_ctx = X509_STORE_CTX(*(X509_STORE_CTX*)ctx);
      int ret = X509_verify_cert(&store_ctx);
      //do more verification
      return ret;
}
m_pAFEngine->SetCertificateVerificationCallback(custom_callback);