class Connection

  • Article 
class Connection
  : public std::enable_shared_from_this< Connection >

Connection is a proxy class for managing connection to the speech service of the specified Recognizer. By default, a Recognizer autonomously manages connection to service when needed. The Connection class provides additional methods for users to explicitly open or close a connection and to subscribe to connection status changes. The use of Connection is optional. It is intended for scenarios where fine tuning of application behavior based on connection status is needed. Users can optionally call Open() to manually initiate a service connection before starting recognition on the Recognizer associated with this Connection. After starting a recognition, calling Open() or Close() might fail. This will not impact the Recognizer or the ongoing recognition. Connection might drop for various reasons, the Recognizer will always try to reinstitute the connection as required to guarantee ongoing operations. In all these cases Connected/Disconnected events will indicate the change of the connection status. Updated in version 1.17.0.

Members

Connected

Syntax: public EventSignal< constConnectionEventArgs & > Connected;

The Connected event to indicate that the recognizer is connected to service.

Disconnected

Syntax: public EventSignal< constConnectionEventArgs & > Disconnected;

The Disconnected event to indicate that the recognizer is disconnected from service.

MessageReceived

Syntax: public EventSignal< constConnectionMessageEventArgs & > MessageReceived;

The MessageReceived event to indicate that the underlying protocol received a message from the service. Added in version 1.10.0.

Open

Syntax: public inline void Open ( bool forContinuousRecognition );

Starts to set up connection to the service. Users can optionally call Open() to manually set up a connection in advance before starting recognition/synthesis on the Recognizer/Synthesizer associated with this Connection. After starting recognition, calling Open() might fail, depending on the process state of the Recognizer/Synthesizer. But the failure does not affect the state of the associated Recognizer/Synthesizer. Note: On return, the connection might not be ready yet. Please subscribe to the Connected event to be notified when the connection is established.

Parameters

  • forContinuousRecognition Indicates whether the connection is used for continuous recognition or single-shot recognition. It takes no effect if the connection is from SpeechSynthsizer.

Close

Syntax: public inline void Close ( );

Closes the connection the service. Users can optionally call Close() to manually shutdown the connection of the associated Recognizer/Synthesizer. The call might fail, depending on the process state of the Recognizer/Synthesizer. But the failure does not affect the state of the associated Recognizer/Synthesizer.

SetMessageProperty

Syntax: public inline void SetMessageProperty ( const std::string & path , const std::string & propertyName , const std::string & propertyValue );

Appends a parameter in a message to service. This method doesn't work for the connection of SpeechSynthesizer. Added in version 1.7.0.

Parameters

  • path the message path.

  • propertyName Name of the property.

  • propertyValue Value of the property. This is a json string.

Returns

void.

SendMessageAsync

Syntax: public inline std::future< void > SendMessageAsync ( const std::string & path , const std::string & payload );

Send a message to the speech service. This method doesn't work for the connection of SpeechSynthesizer. Added in version 1.7.0.

Parameters

  • path The path of the message.

  • payload The payload of the message. This is a json string.

Returns

An empty future.

SendMessageAsync

Syntax: public inline std::future< void > SendMessageAsync ( const std::string & path , uint8_t * payload , uint32_t size );

Send a binary message to the speech service. This method doesn't work for the connection of SpeechSynthesizer. Added in version 1.10.0.

Parameters

  • path The path of the message.

  • payload The binary payload of the message.

  • size The size of the binary payload.

Returns

An empty future.

Connection

Syntax: public inline explicit Connection ( SPXCONNECTIONHANDLE handle );

Internal constructor. Creates a new instance using the provided handle.

Parameters

  • handle The connection handle.

~Connection

Syntax: public inline ~Connection ( );

Destructor.

FromRecognizer

Syntax: public inline static std::shared_ptr< Connection > FromRecognizer ( std::shared_ptr< Recognizer > recognizer );

Gets the Connection instance from the specified recognizer.

Parameters

  • recognizer The recognizer associated with the connection.

Returns

The Connection instance of the recognizer.

FromConversationTranslator

Syntax: public inline static std::shared_ptr< Connection > FromConversationTranslator ( std::shared_ptr< Transcription::ConversationTranslator > convTrans );

Gets the Connection instance from the specified conversation translator.

Parameters

  • convTrans The conversation translator associated with the connection.

Returns

The Connection instance of the conversation translator.

FromDialogServiceConnector

Syntax: public inline static std::shared_ptr< Connection > FromDialogServiceConnector ( std::shared_ptr< Dialog::DialogServiceConnector > dialogServiceConnector );

Gets the Connection instance from the specified dialog service connector, used for observing and managing connection and disconnection from the speech service.

Parameters

  • dialogServiceConnector The dialog service connector associated with the connection.

Returns

The Connection instance of the dialog service connector.

FromSpeechSynthesizer

Syntax: public inline static std::shared_ptr< Connection > FromSpeechSynthesizer ( std::shared_ptr< SpeechSynthesizer > synthesizer );

Gets the Connection instance from the specified speech synthesizer. Added in version 1.17.0.

Parameters

  • synthesizer The speech synthesizer associated with the connection.

Returns

The Connection instance of the speech synthesizer.