ARTRealtimeChannelProtocol

Objective-C

@protocol ARTRealtimeChannelProtocol <ARTChannelProtocol>

Swift

protocol ARTRealtimeChannelProtocol : ARTChannelProtocol

The protocol upon which the ARTRealtimeChannel is implemented. Also embeds ARTEventEmitter.

  • The current ARTRealtimeChannelState of the channel.

    Declaration

    Objective-C

    @property (readonly) ARTRealtimeChannelState state;

    Swift

    var state: ARTRealtimeChannelState { get }

  • An ARTErrorInfo object describing the last error which occurred on the channel, if any.

    Declaration

    Objective-C

    @property (readonly, nullable) ARTErrorInfo *errorReason;

    Swift

    var errorReason: ARTErrorInfo? { get }

  • A shortcut for the -[ARTRealtimeChannelProtocol attach:] method.

    Declaration

    Objective-C

    - (void)attach;

    Swift

    func attach()

  • Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel are received by any channel listeners registered using -[ARTRealtimeChannelProtocol subscribe:]. Any resulting channel state change will be emitted to any listeners registered using the -[ARTEventEmitter on:] or -[ARTEventEmitter once:] methods. A callback may optionally be passed in to this call to be notified of success or failure of the operation. As a convenience, attach: is called implicitly if -[ARTRealtimeChannelProtocol subscribe:] for the channel is called, or -[ARTRealtimePresenceProtocol enter:] or -[ARTRealtimePresenceProtocol subscribe:] are called on the ARTRealtimePresence object for this channel.

    Declaration

    Objective-C

    - (void)attach:(nullable ARTCallback)callback;

    Swift

    func attach(_ callback: ARTCallback? = nil)

    Parameters

    callback

    A success or failure callback function.

  • A shortcut for the -[ARTRealtimeChannelProtocol detach:] method.

    Declaration

    Objective-C

    - (void)detach;

    Swift

    func detach()

  • Detach from this channel. Any resulting channel state change is emitted to any listeners registered using the -[ARTEventEmitter on:] or -[ARTEventEmitter once:] methods. A callback may optionally be passed in to this call to be notified of success or failure of the operation. Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes.

    Declaration

    Objective-C

    - (void)detach:(nullable ARTCallback)callback;

    Swift

    func detach(_ callback: ARTCallback? = nil)

    Parameters

    callback

    A success or failure callback function.

  • Registers a listener for messages on this channel. The caller supplies a listener function, which is called each time one or more messages arrives on the channel.

    Declaration

    Objective-C

    - (ARTEventListener *_Nullable)subscribe:(nonnull ARTMessageCallback)callback;

    Swift

    func subscribe(_ callback: @escaping ARTMessageCallback) -> ARTEventListener?

    Parameters

    callback

    An event listener function.

    Return Value

    An ARTEventListener object.

  • Registers a listener for messages on this channel. The caller supplies a listener function, which is called each time one or more messages arrives on the channel. An attach callback may optionally be passed in to this call to be notified of success or failure of the channel -[ARTRealtimeChannelProtocol attach] operation.

    Declaration

    Objective-C

    - (ARTEventListener *_Nullable)
    subscribeWithAttachCallback:(nullable ARTCallback)onAttach
                       callback:(nonnull ARTMessageCallback)callback;

    Swift

    func subscribe(attachCallback onAttach: ARTCallback?, callback: @escaping ARTMessageCallback) -> ARTEventListener?

    Parameters

    onAttach

    An attach callback function.
    callback

    An event listener function.

    Return Value

    An ARTEventListener object.

  • Registers a listener for messages with a given event name on this channel. The caller supplies a listener function, which is called each time one or more matching messages arrives on the channel.

    Declaration

    Objective-C

    - (ARTEventListener *_Nullable)subscribe:(nonnull NSString *)name
                                callback:(nonnull ARTMessageCallback)callback;

    Swift

    func subscribe(_ name: String, callback: @escaping ARTMessageCallback) -> ARTEventListener?

    Parameters

    name

    The event name.
    callback

    An event listener function.

    Return Value

    An ARTEventListener object.

  • Registers a listener for messages with a given event name on this channel. The caller supplies a listener function, which is called each time one or more matching messages arrives on the channel. A callback may optionally be passed in to this call to be notified of success or failure of the channel -[ARTRealtimeChannelProtocol attach] operation.

    Declaration

    Objective-C

    - (ARTEventListener *_Nullable)subscribe:(nonnull NSString *)name
                                onAttach:(nullable ARTCallback)onAttach
                                callback:(nonnull ARTMessageCallback)callback;

    Swift

    func subscribe(_ name: String, onAttach: ARTCallback?, callback: @escaping ARTMessageCallback) -> ARTEventListener?

    Parameters

    name

    The event name.
    callback

    An event listener function.

    Return Value

    An ARTEventListener object.

  • Deregisters all listeners to messages on this channel. This removes all earlier subscriptions.

    Declaration

    Objective-C

    - (void)unsubscribe;

    Swift

    func unsubscribe()

  • Deregisters the given listener (for any/all event names). This removes an earlier subscription.

    Declaration

    Objective-C

    - (void)unsubscribe:(ARTEventListener *_Nullable)listener;

    Swift

    func unsubscribe(_ listener: ARTEventListener?)

    Parameters

    listener

    An event listener object to unsubscribe.

  • Deregisters the given listener for the specified event name. This removes an earlier event-specific subscription.

    Declaration

    Objective-C

    - (void)unsubscribe:(nonnull NSString *)name
           listener:(ARTEventListener *_Nullable)listener;

    Swift

    func unsubscribe(_ name: String, listener: ARTEventListener?)

    Parameters

    name

    The event name.
    listener

    An event listener object to unsubscribe.

  • Retrieves an ARTPaginatedResult object, containing an array of historical ARTMessage objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past.

    Declaration

    Objective-C

    - (BOOL)history:(ARTRealtimeHistoryQuery *_Nullable)query
       callback:(nonnull ARTPaginatedMessagesCallback)callback
          error:(NSError *_Nullable *_Nullable)errorPtr;

    Swift

    func history(_ query: ARTRealtimeHistoryQuery?, callback: @escaping ARTPaginatedMessagesCallback) throws

    Parameters

    query
    callback

    A callback for retriving an ARTPaginatedResult object with an array of ARTMessage objects.
    errorPtr

    A reference to the NSError object where an error information will be saved in case of failure.

    Return Value

    In case of failure returns false and the error information can be retrived via the error parameter.

  • Sets the ARTRealtimeChannelOptions for the channel. An optional callback may be provided to notify of the success or failure of the operation.

    Declaration

    Objective-C

    - (void)setOptions:(ARTRealtimeChannelOptions *_Nullable)options
          callback:(nullable ARTCallback)callback;

    Swift

    func setOptions(_ options: ARTRealtimeChannelOptions?, callback: ARTCallback? = nil)

    Parameters

    options
    callback

    A success or failure callback function.

ARTEventEmitter