Edit

PartyLocalDevice::CreateChatControl

  • Article

Queues an asynchronous operation to create a local chat control for the specified user.

Syntax

PartyError CreateChatControl(  
    const PartyLocalUser* localUser,  
    PartyString languageCode,  
    void* asyncIdentifier,  
    PartyLocalChatControl** localChatControl  
)

Parameters

localUser   PartyLocalUser*

The local user for the new local chat control.

languageCode   PartyString
optional

The optional language to use.

asyncIdentifier   void*
optional

An optional, app-defined, pointer-sized context value that can be used to associate the completion state change with this call.

localChatControl   PartyLocalChatControl**
optional, library-allocated output

The optional, output local chat control.

Return value

PartyError

c_partyErrorSuccess if the asynchronous operation to create a chat control began, or an error code otherwise. If this method fails, no related state changes will be generated. The human-readable form of the error code can be retrieved via PartyManager::GetErrorMessage().

Remarks

If this method returns success, a PartyCreateChatControlCompletedStateChange will be generated to provide the result of the asynchronous operation. If the asynchronous operation succeeds, a PartyChatControlCreatedStateChange will be generated. If the operation fails, a PartyChatControlDestroyedStateChange will be generated. This method itself does not make the chat control visible to any remote devices. To announce this chat control to remote devices, the title should call PartyNetwork::ConnectChatControl().

On successful return, this method invalidates the memory for any array previously returned by PartyManager::GetChatControls() or PartyDevice::GetChatControls() for the local device, as it synchronously adds the new chat control to the arrays. PartyManager::StartProcessingStateChanges() also invalidates the memory for these arrays. The returned localChatControl object will be valid until a PartyChatControlDestroyedStateChange has been generated and all state changes referencing the object have been returned to PartyManager::FinishProcessingStateChanges().

The language associated with this chat control can optionally be specified via the languageCode parameter. If no language is specified, the user's default, as determined by the platform, will be used. The language is used as the spoken language associated with this chat control for transcription and the target language for incoming translations. If the language code specified is en-US, for instance, the input audio to this chat control will be treated as the English (United States) language and transcribed as such. If translation is enabled via either PartyLocalChatControl::SetTranscriptionOptions() or PartyLocalChatControl::SetTextChatOptions(), the incoming voice chat transcriptions and/or text chat will be translated to English (United States).

The language code should be in BCP 47 format; supported language codes are enumerated in Language support. Specifying an unsupported or invalid language code will not cause this method to fail, but will result in failure to generate transcriptions associated with this chat control. The language code used with this method can be queried via PartyLocalChatControl::GetLanguage().

Requirements

Header: Party.h

See also

PartyLocalDevice
PartyCreateChatControlCompletedStateChange
PartyChatControlCreatedStateChange
PartyChatControlDestroyedStateChange
PartyManager::GetChatControls
PartyDevice::GetChatControls
PartyNetwork::ConnectChatControl
PartyLocalChatControl::GetLanguage
PartyLocalChatControl::SetTranscriptionOptions
PartyLocalChatControl::SetTranscriptionOptions