Class SPXConnection

  • Article

Declaration

@class SPXConnection : NSObject;

Description

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.

Added in version 1.2.0.

Methods

initFromRecognizer:

Gets the Connection instance from the specified recognizer.

- (instancetype _Nullable)initFromRecognizer:(SPXRecognizer * _Nonnull)recognizer

Parameters

  • recognizer - The recognizer associated with the connection.

Returns

The Connection instance of the recognizer.

initFromRecognizer:error:

Gets the Connection instance from the specified recognizer.

Added in version 1.6.0.

- (instancetype _Nullable)initFromRecognizer:(SPXRecognizer * _Nonnull)recognizer
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • recognizer - The recognizer associated with the connection.
  • outError - error information.

Returns

The Connection instance of the recognizer.

initFromConversationTranslator:

Gets the Connection instance from the specified conversation translator.

- (instancetype _Nullable)initFromConversationTranslator:(SPXConversationTranslator * _Nonnull)translator

Parameters

  • translator - The conversation translator associated with the connection.

Returns

The Connection instance of the conversation translator.

initFromConversationTranslator:error:

Gets the Connection instance from the specified conversation translator.

Added in version 1.13.0.

- (instancetype _Nullable)initFromConversationTranslator:(SPXConversationTranslator * _Nonnull)translator
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • translator - The conversation translator associated with the connection.
  • outError - error information.

Returns

The Connection instance of the conversation translator.

initFromSpeechSynthesizer:

Gets the Connection instance from the specified speech synthesizer.

Added in version 1.17.0

- (instancetype _Nullable)initFromSpeechSynthesizer:(SPXSpeechSynthesizer * _Nonnull)synthesizer

Parameters

  • synthesizer - The speech synthesizer associated with the connection.

Returns

The Connection instance of the speech synthesizer.

initFromSpeechSynthesizer:error:

Gets the Connection instance from the specified speech synthesizer.

Added in version 1.17.0

- (instancetype _Nullable)initFromSpeechSynthesizer:(SPXSpeechSynthesizer * _Nonnull)synthesizer
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • synthesizer - The speech synthesizer associated with the connection.
  • outError - error information.

Returns

The Connection instance of the speech synthesizer.

initFromDialogServiceConnector:

Initializes a Connection instance from the specified DialogServiceConnector.

- (instancetype _Nonnull)initFromDialogServiceConnector:(SPXDialogServiceConnector * _Nonnull)dialogServiceConnector

Parameters

  • dialogServiceConnector - the DialogServiceConnector instance associated with the connection.

Returns

a Connection instance associated with the provided DialogServiceConnector.

initFromDialogServiceConnector:error:

Initializes a Connection instance from the specified DialogServiceConnector.

- (instancetype _Nullable)initFromDialogServiceConnector:(SPXDialogServiceConnector * _Nonnull)dialogServiceConnector
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • dialogServiceConnector - the DialogServiceConnector instance associated with the connection.
  • outError - error information.

Returns

a Connection instance associated with the provided DialogServiceConnector.

open:

Starts to set up connection to the service. Users can optionally call Open() to manually set up a connection in advance before starting recognition on the Recognizer associated with this Connection. After starting recognition, calling Open() might fail, depending on the process state of the Recognizer. But the failure does not affect the state of the associated Recognizer.

Note: On return, the connection might not be ready yet. Please subscribe to the Connected event to be notified when the connection is established.

- (void)open:(BOOL)forContinuousRecognition

Parameters

  • forContinuousRecognition - indicates whether the connection is used for continuous recognition or single-shot recognition.

close

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

- (void)close

addConnectedEventHandler:

Subscribes to the Connected event which indicates that the recognizer is connected to service. In order to receive the Connected event after subscribing to it, the Connection object itself needs to be alive. If the Connection object owning this event is out of its life time, all subscribed events won't be delivered.

- (void)addConnectedEventHandler:(SPXConnectionEventHandler _Nonnull)eventHandler

addDisconnectedEventHandler:

Subscribe to the Disconnected event which indicates that the recognizer is disconnected from service. In order to receive the Disconnected event after subscribing to it, the Connection object itself needs to be alive. If the Connection object owning this event is out of its life time, all subscribed events won't be delivered.

- (void)addDisconnectedEventHandler:(SPXConnectionEventHandler _Nonnull)eventHandler

addMessageReceivedEventHandler:

Subscribes to the ConnectionMessageReceived event which indicates that a message is received from the service. In order to receive the ConnectionMessageReceived event after subscribing to it, the Connection object itself needs to be alive. If the Connection object owning this event is out of its life time, all subscribed events won't be delivered.

- (void)addMessageReceivedEventHandler:(SPXConnectionMessageEventHandler _Nonnull)eventHandler

setMessageProperty:propertyName:propertyValue:

Appends a parameter in a message to service. Added in version 1.9.0.

Note: This method doesn't work for the connection of SPXSpeechSynthesizer.

- (void)setMessageProperty:(NSString * _Nonnull)path propertyName:(NSString * _Nonnull)propertyName
    propertyValue:(NSString * _Nonnull)propertyValue

Parameters

  • path - The path of the message.
  • propertyName - The propertyName of the message.
  • propertyValue - The propertyValue of the message as a json string.

setMessageProperty:propertyName:propertyValue:error:

Appends a parameter in a message to service. Added in version 1.17.0.

Note: This method doesn't work for the connection of SPXSpeechSynthesizer.

- (BOOL)setMessageProperty:(NSString * _Nonnull)path propertyName:(NSString * _Nonnull)propertyName
    propertyValue:(NSString * _Nonnull)propertyValue
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • path - The path of the message.
  • propertyName - The propertyName of the message.
  • propertyValue - The propertyValue of the message as a json string.
  • outError - error information.

sendMessage:payload:

Send message to service. Added in version 1.9.0.

Note: This method doesn't work for the connection of SPXSpeechSynthesizer.

- (void)sendMessage:(NSString * _Nonnull)path payload:(NSString * _Nonnull)payload

Parameters

  • path - The path of the message.
  • payload - The payload of the message as a json string.

sendMessage:payload:error:

Send message to service. Added in version 1.9.0.

Note: This method doesn't work for the connection of SPXSpeechSynthesizer.

- (BOOL)sendMessage:(NSString * _Nonnull)path payload:(NSString * _Nonnull)payload
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • path - The path of the message.
  • payload - The payload of the message as a json string.
  • outError - error information.

Returns

The boolean value indicating successful operation.