10.2. Basic Features of PiaChat

Introduction

This section describes the basic PiaChat features.

Setup

Before initializing PiaChat, you must initialize communication modules such as PiaInet and PiaTransport. For more information about initializing modules other than PiaChat, see the programming manuals for each module and the API reference.

Initialization

Initialize the PiaChat module, instantiate the VoiceProtocol instance, and then initialize that VoiceProtocol instance. The VoiceProtocol class uses transport::UnreliableProtocol internally. Specify a port number for the UnreliableProtocol that VoiceProtocol uses in the port member of the Setting structure that is passed to VoiceProtocol::Initialize(). If your application also uses UnreliableProtocol outside of the PiaChat module, you must specify a different port number.

Code 10-1. Initializing PiaChat
// Assume PiaInet, PiaTransport, and any other necessary modules have already been initialized.

// Now initialize the PiaChat module.
result = nn::pia::chat::Initialize();
PIA_ASSERT(result.IsSuccess());

// Start PiaChat setup.
result = nn::pia::chat::BeginSetup();
PIA_ASSERT(result.IsSuccess());

// Create an instance of the VoiceProtocol class and get its handle.
nn::pia::transport::Transport* pTransport = nn::pia::transport::Transport::GetInstance();
PIA_ASSERT(PIA_IS_VALID_POINTER(pTransport));
PIA_ASSERT(m_VoiceProtocolHandle == 0);
m_VoiceProtocolHandle = pTransport->CreateProtocol<nn::pia::chat::VoiceProtocol>();
PIA_ASSERT(m_VoiceProtocolHandle != 0);

// Initialize the VoiceProtocol class using the Setting structure.
// In most cases, the default values can be used. However, if you need to change parameters such as the codec or the audio frame length,
// set the desired values in the Setting structure before calling the Initialize() function.
nn::pia::chat::VoiceProtocol::Setting setting;
result = pTransport->GetProtocol<nn::pia::chat::VoiceProtocol>(m_VoiceProtocolHandle)->Initialize(setting);
PIA_ASSERT(result.IsSuccess());

// Finish PiaChat setup.
result = nn::pia::chat::EndSetup();
PIA_ASSERT(result.IsSuccess());

Starting Chat

To join the conference, the stations must add each other as participants (clients) in the conference. Use the VoiceProtocol::AddConferenceClient() function to add stations to the conference.

Code 10-2. Adding Stations to the Conference
pTransport->GetProtocol<nn::pia::chat::VoiceProtocol>(m_VoiceProtocolHandle)->AddConferenceClient( peerStationId );

Sending Voice Data

Use the VoiceProtocol::Send() function to periodically send voice data obtained by the microphone or other audio input devices. The method for getting voice data varies by platform and is not fully described in this documentation. For more information, see the sample demos.

Code 10-3. Sending Voice Data
pTransport->GetProtocol<nn::pia::chat::VoiceProtocol>(m_VoiceProtocolHandle)->Send(static_cast<void*>(sendBuff), samplingNum);

Receiving Voice Data

Use the VoiceProtocol::Receive() function to receive voice data. The method for playing voice data varies by platform and is not fully described in this documentation. For more information, see the sample demos.

Code 10-4. Receiving Voice Data
pTransport->GetProtocol<nn::pia::chat::VoiceProtocol>(m_VoiceProtocolHandle)->Receive(static_cast<void*>(recvBuff), frameDataSize, NULL );

Stopping Chat

Use the VoiceProtocol::RemoveConferenceClient() function to remove a specified station from the conference. Call the VoiceProtocol::AddConferenceClient() function again to add that station back to the chat session.

Code 10-5. Removing a Station From the Conference
pTransport->GetProtocol<nn::pia::chat::VoiceProtocol>(m_VoiceProtocolHandle)->RemoveConferenceClient(peerStationId);

Finalization

Finalize the PiaChat module before finalizing the PiaInet or PiaTransport modules.

Code 10-6. Finalizing PiaChat
nn::pia::transport::Transport* pTransport = nn::pia::transport::Transport::GetInstance();
if(PIA_IS_VALID_POINTER(pTransport))
{
    // Get a pointer to the instance of the VoiceProtocol class. Finalize and destroy that instance.
    nn::pia::chat::VoiceProtocol* pVoiceProtocol = GetProtocol<nn::pia::chat::VoiceProtocol>(m_VoiceProtocolHandle);
    if(PIA_IS_VALID_POINTER(pVoiceProtocol))
    {
        pVoiceProtocol->Finalize();
        pTransport->DestroyProtocol(m_VoiceProtocolHandle);
        m_VoiceProtocolHandle = 0;
    }
}

// Finalize the PiaChat module.
nn::pia::chat::Finalize();