Documentation

Support

Vivox Unreal SDK

IChannelSession

Reference the IChannelSession interface for managing voice and text in channels.

Read time 8 minutes

Last updated 2 days ago

A connection to a channel.

#include <IChannelSession.h>

Public Types

	Name
typedef FDelegateBeginConnectCompleted::FDelegate	FOnBeginConnectCompletedDelegate The delegate called when `BeginConnect()` completes.
typedef FDelegateBeginSetAudioConnectedCompleted::FDelegate	FOnBeginSetAudioConnectedCompletedDelegate The delegate called when `BeginSetAudioConnected()` completes.
typedef FDelegateBeginSetTextConnectedCompleted::FDelegate	FOnBeginSetTextConnectedCompletedDelegate The delegate called when `BeginSetTextConnected()` completes.
typedef FDelegateBeginSendTextCompleted::FDelegate	FOnBeginSendTextCompletedDelegate The delegate called when `BeginSendText()` completes.
typedef FDelegateBeginSetChannelTranscriptionCompleted::FDelegate	FOnBeginSetChannelTranscriptionCompletedDelegate The delegate called when `BeginSetChannelTranscription()` completes.

Public Functions

	Name
virtual ILoginSession &	Parent() =0 The login session that owns this channel session.
virtual ConnectionState	AudioState() const =0 The state of the audio portion of this channel session.
virtual ConnectionState	TextState() const =0 The state of the text portion of this channel session.
virtual ConnectionState	ChannelState() const =0 The state of the overall connection of this channel session.
virtual const TMap< FString, IParticipant * > &	Participants() const =0 The list of participants in this channel, including the current user.
virtual bool	Typing() const =0 Indicates if this user is typing.
virtual void	SetTyping(bool value) =0 Set whether this user is typing. Setting or clearing this causes `IParticipantProperties.IsTyping()` to change for other users in the channel.
virtual bool	IsTransmitting() const =0 Indicates that microphone audio and injected audio will transmit to this session.
virtual ChannelId	Channel() const =0 The channel ID of this session.
virtual VivoxCoreError	BeginConnect(bool connectAudio, bool connectText, bool switchTransmission, const FString & accessToken, FOnBeginConnectCompletedDelegate theDelegate =FOnBeginConnectCompletedDelegate()) =0 Perform the initial connection to the channel.
virtual void	Disconnect(bool deleteOnDisconnect =false) =0 Disconnect the user from this channel.
virtual VivoxCoreError	BeginSetAudioConnected(bool value, bool switchTransmission, FOnBeginSetAudioConnectedCompletedDelegate callback =FOnBeginSetAudioConnectedCompletedDelegate()) =0 Add or remove audio from the channel session.
virtual VivoxCoreError	BeginSetTextConnected(bool value, FOnBeginSetTextConnectedCompletedDelegate callback =FOnBeginSetTextConnectedCompletedDelegate()) =0 Add or remove text from the channel session.
virtual VivoxCoreError	BeginSendText(const FString & language, const FString & message, const FString & applicationStanzaNamespace =FString(), const FString & applicationStanzaBody =FString(), FOnBeginSendTextCompletedDelegate theDelegate =FOnBeginSendTextCompletedDelegate()) =0 Send a message to this channel.
virtual VivoxCoreError	BeginSendText(const FString & message, FOnBeginSendTextCompletedDelegate theDelegate =FOnBeginSendTextCompletedDelegate()) =0 Send a message to this channel.
virtual VivoxCoreError	Set3DPosition(const FVector & speakerPosition, const FVector & listenerPosition, const FVector & listenerForwardVector, const FVector & listenerUpVector) =0 Set the 3D position of the speaker, and the position and orientation of the listener.
virtual FString	GetConnectToken(const FString & tokenSigningKey, FTimespan tokenExpirationDuration) const =0 Get a token that can be used to connect to this channel.
virtual bool	IsSessionBeingTranscribed() const =0 Indicates that this session is being transcibed.
virtual VivoxCoreError	BeginSetChannelTranscription(bool value, const FString & accessToken, FOnBeginSetChannelTranscriptionCompletedDelegate callback =FOnBeginSetChannelTranscriptionCompletedDelegate()) =0 Enable or disable transcription for this channel session.
virtual FString	GetTranscriptionToken(const FString & tokenSigningKey, FTimespan tokenExpirationDuration) const =0 Get a token that can be used to enable or disable transcription for this channel.

Public Attributes

	Name
AudioStateChanged	EventAudioStateChanged This event fires when the audio state changes.
TextStateChanged	EventTextStateChanged This event fires when the text state changes.
ChannelStateChanged	EventChannelStateChanged This event fires when the channel connection state changes.
AfterParticipantAdded	EventAfterParticipantAdded This event is raised after a participant is added to the `Participants()` collection.
BeforeParticipantRemoved	EventBeforeParticipantRemoved This event is raised before a participant is removed from the `Participants()` collection.
AfterParticipantUpdated	EventAfterParticipantUpdated This event is raised after a participant property changes.
TextMessageReceived	EventTextMessageReceived An event that indicates another player has sent the channel a text message.
TranscribedMessageReceived	EventTranscribedMessageReceived An event that indicates incoming transcribed text from a participant in a channel session.

Public Types Documentation

typedef FOnBeginConnectCompletedDelegate


typedef FDelegateBeginConnectCompleted::FDelegate IChannelSession::FOnBeginConnectCompletedDelegate;

The delegate called when

BeginConnect()

completes.

typedef FOnBeginSetAudioConnectedCompletedDelegate


typedef FDelegateBeginSetAudioConnectedCompleted::FDelegate IChannelSession::FOnBeginSetAudioConnectedCompletedDelegate;

The delegate called when

BeginSetAudioConnected()

completes.

typedef FOnBeginSetTextConnectedCompletedDelegate


typedef FDelegateBeginSetTextConnectedCompleted::FDelegate IChannelSession::FOnBeginSetTextConnectedCompletedDelegate;

The delegate called when BeginSetTextConnected()` completes.

typedef FOnBeginSendTextCompletedDelegate


typedef FDelegateBeginSendTextCompleted::FDelegate IChannelSession::FOnBeginSendTextCompletedDelegate;

The delegate called when

BeginSendText()

completes.

typedef FOnBeginSetChannelTranscriptionCompletedDelegate


typedef FDelegateBeginSetChannelTranscriptionCompleted::FDelegate IChannelSession::FOnBeginSetChannelTranscriptionCompletedDelegate;

The delegate called when

BeginSetChannelTranscription()

completes.

Public Functions Documentation

function Parent


virtual ILoginSession & Parent() =0

The login session that owns this channel session.

function AudioState


virtual ConnectionState AudioState() const =0

The state of the audio portion of this channel session. Remark: Changes to this value can occur at any time due to network or moderator events.

function TextState


virtual ConnectionState TextState() const =0

The state of the text portion of this channel session. Remark: Changes to this value can occur at any time due to network or moderator events.

function ChannelState


virtual ConnectionState ChannelState() const =0

The state of the overall connection of this channel session. Remark: Changes to this value can occur at any time due to network or moderator events. It is not safe to join this user to another channel or to rejoin this channel while this property is in the ConnectionState::Disconnecting state, unless another

IChannelSession

is already connected. If not connected to another channel, then calls to BeginConnect() for this user should be avoided until this property is set to ConnectionState::Disconnected. Use EventChannelStateChanged to monitor state changes.

function Participants


virtual const TMap< FString, IParticipant * > & Participants() const =0

The list of participants in this channel, including the current user. Remark: Changes to this list can occur at any time. Key equals the participant's AccountId::Name().

function Typing


virtual bool Typing() const =0

Indicates if this user is typing.

function SetTyping


virtual void SetTyping(    bool value) =0

Set whether this user is typing. Setting or clearing this causes

IParticipantProperties.IsTyping()

to change for other users in the channel.

function IsTransmitting


virtual bool IsTransmitting() const =0

Indicates that microphone audio and injected audio will transmit to this session. See: ILoginSession::SetTransmissionMode()

function Channel


virtual ChannelId Channel() const =0

The channel ID of this session.

function BeginConnect


virtual VivoxCoreError BeginConnect(    bool connectAudio,    bool connectText,    bool switchTransmission,    const FString & accessToken,    FOnBeginConnectCompletedDelegate theDelegate =FOnBeginConnectCompletedDelegate()) =0

Perform the initial connection to the channel. Parameters:

connectAudio True to connect audio.
connectText True to connect text.
switchTransmission When connected, transmit only into this channel. This overrides and changes the TransmissionMode set in ILoginSession.
accessToken The access token that grants the user access to the channel.
theDelegate A delegate to call when this operation completes.

Return: VxErrorInvalidArgument if:

accessToken is empty
connectAudio and connectText are both false
Channel().IsValid() is false

Remark: Developers that do not have secure communications requirements can use GetConnectToken() to generate the required access token.

function Disconnect


virtual void Disconnect(    bool deleteOnDisconnect =false) =0

Disconnect the user from this channel. Parameters:

deleteOnDisconnect Set to true to cause the channel to be removed from ILoginSession::ChannelSessions() immediately after sending out the EventChannelStateChanged event to disconnected.

See: ILoginSession::DeleteChannelSession() Remark: You should not try to join this user to another channel or to rejoin this channel while this session's ChannelState() property is set to ConnectionState::Disconnecting, unless another

IChannelSession

is already connected. If not connected to another channel, use EventChannelStateChanged to monitor property changes and wait for ConnectionState::Disconnected before calling BeginConnect() again. This object remains in the ILoginSession::ChannelSessions() list in the disconnected state. Use ILoginSession::DeleteChannelSession() to remove it from the list. Note: If transmission is specifically set to this channel, then TransmissionMode changes to "None" when disconnected.

function BeginSetAudioConnected


virtual VivoxCoreError BeginSetAudioConnected(    bool value,    bool switchTransmission,    FOnBeginSetAudioConnectedCompletedDelegate callback =FOnBeginSetAudioConnectedCompletedDelegate()) =0

Add or remove audio from the channel session. Parameters:

value True to add audio, false to remove audio.
switchTransmission When audio is added, transmit only into this channel. This overrides and changes the TransmissionMode set in ILoginSession.
callback A delegate to call when this operation completes.

Return: 0 for success. Remark: If transmission is specifically set to this channel, then when audio is removed, TransmissionMode changes to "None".

function BeginSetTextConnected


virtual VivoxCoreError BeginSetTextConnected(    bool value,    FOnBeginSetTextConnectedCompletedDelegate callback =FOnBeginSetTextConnectedCompletedDelegate()) =0

Add or remove text from the channel session. Parameters:

value True to add text, false to remove text.
callback A delegate to call when this operation completes.

Return: 0 for success.

function BeginSendText


virtual VivoxCoreError BeginSendText(    const FString & language,    const FString & message,    const FString & applicationStanzaNamespace =FString(),    const FString & applicationStanzaBody =FString(),    FOnBeginSendTextCompletedDelegate theDelegate =FOnBeginSendTextCompletedDelegate()) =0

Send a message to this channel. Parameters:

language The language of the message, for example, "en". To use the default language ("en" for most systems), set this to null. Note: This must conform to BCP 47 (https://tools.ietf.org/html/bcp47).
message The body of the message.
applicationStanzaNamespace An optional namespace element for additional application data.
applicationStanzaBody The additional application data body.
theDelegate A delegate to call when this operation completes.

Return: 0 for success.

function BeginSendText


virtual VivoxCoreError BeginSendText(    const FString & message,    FOnBeginSendTextCompletedDelegate theDelegate =FOnBeginSendTextCompletedDelegate()) =0

Send a message to this channel. Parameters:

message The body of the message.
theDelegate A delegate to call when this operation completes.

Return: 0 for success.

function Set3DPosition


virtual VivoxCoreError Set3DPosition(    const FVector & speakerPosition,    const FVector & listenerPosition,    const FVector & listenerForwardVector,    const FVector & listenerUpVector) =0

Set the 3D position of the speaker, and the position and orientation of the listener. Parameters:

speakerPosition The position of the virtual "mouth".
listenerPosition The position of the virtual "ear".
listenerForwardVector A unit vector that represents the forward (X) direction, or heading, of the listener.
listenerUpVector A unit vector that represents the up (Z) direction of the listener. Use FVector(0, 0, 1) for a "global" up in world space.

Return: 0 for success, or VxErrorInvalidState if

IChannelSession()

AudioState is not Connected or if ChannelType is not Positional. Remark: For most applications, the speaker and listener positions are expected to be the same. Note that the SDK supports the decoupling of these positions (for example, the virtual "mouth" might be where the avatar is located, and the virtual "ears" are where the camera view is located). Because this is the most frequently used VivoxCore method (when using positional channels), you do not see any voice server response logged unless an error occurs (no reply is sent for success).

function GetConnectToken


virtual FString GetConnectToken(    const FString & tokenSigningKey,    FTimespan tokenExpirationDuration) const =0

Get a token that can be used to connect to this channel. Parameters:

tokenSigningKey The key that corresponds to the issuer for this account that is used to sign the token.
tokenExpirationDuration The length of time the token is valid for.

Return: A token that can be used to join this channel. Remark: This is only to be used by applications without secure communications requirements.

function IsSessionBeingTranscribed


virtual bool IsSessionBeingTranscribed() const =0

Indicates that this session is being transcibed. Remark: To set this value, use BeginSetChannelTranscription().

function BeginSetChannelTranscription


virtual VivoxCoreError BeginSetChannelTranscription(    bool value,    const FString & accessToken,    FOnBeginSetChannelTranscriptionCompletedDelegate callback =FOnBeginSetChannelTranscriptionCompletedDelegate()) =0

Enable or disable transcription for this channel session. Parameters:

value True to enable channel transcription, false to disable transcription.
accessToken The access token that grants the user access to set transciption for the channel.
callback A delegate to call when this operation completes.

Return: 0 for success.

function GetTranscriptionToken


virtual FString GetTranscriptionToken(    const FString & tokenSigningKey,    FTimespan tokenExpirationDuration) const =0

Get a token that can be used to enable or disable transcription for this channel. Parameters:

tokenSigningKey The key that corresponds to the issuer for this account that is used to sign the token.
tokenExpirationDuration The length of time the token is valid for.

Return: A token that can be used to set transcriptions in this channel. Remark: This is only to be used by applications without secure communications requirements.

Public Attributes Documentation

variable EventAudioStateChanged


AudioStateChanged EventAudioStateChanged;

This event fires when the audio state changes.

variable EventTextStateChanged


TextStateChanged EventTextStateChanged;

This event fires when the text state changes.

variable EventChannelStateChanged


ChannelStateChanged EventChannelStateChanged;

This event fires when the channel connection state changes.

variable EventAfterParticipantAdded


AfterParticipantAdded EventAfterParticipantAdded;

This event is raised after a participant is added to the

Participants()

collection.

variable EventBeforeParticipantRemoved


BeforeParticipantRemoved EventBeforeParticipantRemoved;

This event is raised before a participant is removed from the

Participants()

collection.

variable EventAfterParticipantUpdated


AfterParticipantUpdated EventAfterParticipantUpdated;

This event is raised after a participant property changes.

variable EventTextMessageReceived


TextMessageReceived EventTextMessageReceived;

An event that indicates another player has sent the channel a text message.

variable EventTranscribedMessageReceived


TranscribedMessageReceived EventTranscribedMessageReceived;

An event that indicates incoming transcribed text from a participant in a channel session.