DITBus

@interface DITBus : NSObject

Send and receive messages with remote Ditto peers in the mesh.

Ditto Bus is separate from the replicated document database. It is used to send one-off messages or create continuous channels with other peers in the mesh, without any persistence. Messages are treated as opaque binary by Ditto and must be created and interpreted by your app.

Possible uses include:

  • Remote control systems
  • Tunnelling other protocols
  • Gaming
  • Voice and video

Ditto Bus communications are always between two distinct peers, 1-to-1, and are offered with various delivery guarantees.

For simple use cases there is a single-message API. These are received on the other peer via DITBusDelegate.

In advanced situations with requirements such as multiple overlapping streams, notification of stream start and end, and backpressure, individual streams can be opened using the openStream function. Once opened, these are symmetric/bidirectional message-oriented communication channels. The remote peer will receive their stream via DITBusDelegate.

  • Delegate for global bus events

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) id<DITBusDelegate> delegate;
  • The dispatch queue on which Bus and BusStream events will be delivered.

    By default this is a separate serial queue. A custom queue may be provided.

    Declaration

    Objective-C

    @property (nonatomic) dispatch_queue_t _Nonnull delegateEventQueue;
  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)init NS_UNAVAILABLE;
  • Send a single bus message to another peer, with no guarantees on delivery.

    A completion closure may be provided which will provide feedback about whether this message was transmitted (but not necessarily received.)

    Declaration

    Objective-C

    - (void)sendSingleUnreliableMessage:(nonnull NSData *)data
                              toAddress:(nonnull DITAddress *)address
                             completion:
                                 (void (^_Nullable)(NSError *_Nullable))completion;
  • Send a single bus message to another peer, taking care that the message is delivered in full, if connectivity permits it.

    A completion closure may be provided which will provide feedback about whether this message was transmitted (but not necessarily received.)

    Declaration

    Objective-C

    - (void)sendSingleReliableMessage:(nonnull NSData *)data
                            toAddress:(nonnull DITAddress *)address
                           completion:
                               (void (^_Nullable)(NSError *_Nullable))completion;
  • Open a dedicated stream handle to a remote peer at the nominated reliability level.

    The completion closure will provide either the successfully-connected stream or an error.

    Make sure to set the delegate property on the new stream immediately when it is received in the completion closure. This ensures that no callbacks will be missed.

    Declaration

    Objective-C

    - (void)openStreamToAddress:(nonnull DITAddress *)address
                    reliability:(DITBusReliability)reliability
                     completion:(nonnull void (^)(DITBusStream *_Nullable,
                                                  NSError *_Nullable))completion;