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;