Documentation

Support

Vivox Core SDK

Vivox Core SDK

Initializing Vivox

How to initialize Vivox.
Read time 3 minutesLast updated 20 hours ago
Use this guide to initialize Vivox and test your integration. The game client must initialize with the Vivox SDK before interacting with it.

1. Set up your message handler

Goal: Create a function to process Vivox messages as they appear. Set up Vivox to handle responses and events via a common callback. Set this callback function via the 
pf_sdk_message_callback
member of the 
vx_sdk_config_t
parameter passed into 
vx_initialize3()
. The void *callback_handle, which is also registered with 
vx_sdk_config_t
, will call the bound method. This can be a pointer to a singleton class that tracks the Vivox state. When the callback occurs, call 
vx_get_message()
(non-blocking) until no more messages are processed. It is unnecessary to handle messages on the thread that generated the notification callback, but you can if you want to. The example below is an implementation of this process: 
void OnResponseOrEventFromSdk() {    int status;    vx_message_base_t *msg;    for (;;) {        status = vx_get_message(&msg);        if (status == VX_GET_MESSAGE_AVAILABLE) {            if (msg->type == msg_event) {                DispatchEvent(reinterpret_cast<vx_evt_base_t *>(msg));            }            else {                DispatchResponse(reinterpret_cast<vx_resp_base_t *>(msg));            }            vx_destroy_message(msg);        }        else if (status == VX_GET_MESSAGE_FAILURE) {        // Handle error here. Occurs if vx_initialize3() has yet to be called.        }        else { /* VX_GET_MESSAGE_NO_MESSAGE */            break;        }    }}
For more details, refer to Message callback.

2. Call initialize

Goal: Initialize the Vivox SDK. Initialize the Vivox SDK by creating a config variable and passing it to 
vx_initialize3()
. Both of these calls will return a response code defined in 
VxcErrors.h
. A successful response returns 
VxErrorSuccess
. 
#include"Vxc.h"#include"VxcErrors.h"vx_sdk_config_t defaultConfig;int status = vx_get_default_config3(&defaultConfig, size of (defaultConfig));if (status != VxErrorSuccess) {    printf("vx_sdk_get_default_config3() returned %d: %s\n", status,    vx_get_error_string(status));    return;}config.pf_sdk_message_callback = &sOnResponseOrEventFromSdk;status = vx_initialize3(&defaultConfig, size of (defaultConfig));if (status != VxErrorSuccess) {    printf("vx_initialize3() returned %d : %s\n", status, vx_get_error_string(status));    return;}// Vivox Client SDK is now initialized
For more details, refer to Initialize the Vivox SDK.

3. Create a connector handle

Goal: Fetch the pre-login server-side configuration file. Create a request object of type 
vx_req_connector_create
, set a 
connector_handle
value of your choosing and wait for the 
vx_resp_connector_create
response before logging in to the Vivox network. This request fetches important pre-login information from your assigned Vivox server. This information is required before logging into the Vivox network. If you have one or more dedicated servers, the 
acct_mgmt_server
value might vary by title and region. 
vx_req_connector_create *req;vx_req_connector_create_create(&req);req->connector_handle = vx_strdup("c1");req->acct_mgmt_server = vx_strdup("https://mt1s.www.vivox.com/api2/");int request_count;int vx_issue_request3_response = vx_issue_request3(&req->base, &request_count);
For more information, refer to Create the connector object.

Verify your implementation

Follow these steps to verify your implementation:
  1. Launch your client application. Navigate past the point where the Vivox SDK should be initialized.
  2. Set a breakpoint on the SDK message callback or observe a client log file.
  3. Add or remove an audio headset multiple times.
  4. Observe that the message callback fires and 
    vx_get_message()
    retrieves events.
  5. Navigate past the point where the 
    connector_create
    request is submitted.
  6. Verify that the message callback picks up a 
    vx_resp_connector_create
    response.
  7. Rerun the 
    connector_create
    test with no internet connection, and verify that error handling and logging work as expected.
When your game client receives an event from the Vivox SDK, your first step is to evaluate if it was successful. For the initialization process, check for success with the 
connector_create
call. If successful, the 
status_code
field will be 0. If it is not zero, your game client should follow the below steps to initiate a retry.

If connector create is unsuccessful

  1. Print an error to debug log or the client event capture location.
  2. Attempt to retry 
    vx_req_connector_create
    initialization.
  3. Delay for 10 seconds between retries.
  4. After 5 failed retries, inform the user that voice chat services are not available.
  5. Retry on the next match or party invite or in 15 minutes, whichever comes first.
  6. Write the failure to a client log or a server log. Include the 
    status_code
    .
For more information on Vivox logs, refer to Vivox Client SDK logs. Once you have verified your implementation you can move on to logging in users.