DITCollection Class Reference


                    
                    
                    name

The name of the collection.

Declaration

Objective-C

@property (nonatomic, readonly) NSString *_Nonnull name;


                    
                    
                    -upsert:error:

Convenience method, same as upsert:writeStrategy:error: where DITWriteStrategyMerge is passed for writeStrategy.

Declaration

Objective-C

- (nullable DITDocumentID *)upsert:
                                (nonnull NSDictionary<NSString *, id> *)content
                             error:(NSError *_Nullable *_Nullable)error;


                    
                    
                    -upsert:writeStrategy:error:

Inserts a new document into the collection and returns its ID. If the document already exists, the behavior is determined by the given writeStrategy.

Declaration

Objective-C

- (nullable DITDocumentID *)upsert:
                                (nonnull NSDictionary<NSString *, id> *)content
                     writeStrategy:(DITWriteStrategy)writeStrategy
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`writeStrategy`	Specifies the desired strategy for inserting a document.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the upserted document, or nil if upsertion failed.


                    
                    
                    -insert:error:

Deprecated

use upsert(:withID:writeStrategy:error:) instead.

Inserts a new document into the collection and returns its ID.

@deprecated use upsert:writeStrategy:error: instead.

Declaration

Objective-C

- (nullable DITDocumentID *)insert:
                                (nonnull NSDictionary<NSString *, id> *)content
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the inserted document, or nil if insertion failed.


                    
                    
                    -insert:withID:error:

Deprecated

use upsert(:withID:writeStrategy:error:) instead.

Inserts a new document into the collection and returns its ID.

@deprecated use upsert:writeStrategy:error: instead.

Declaration

Objective-C

- (nullable DITDocumentID *)insert:
                                (nonnull NSDictionary<NSString *, id> *)content
                            withID:(nullable DITDocumentID *)id
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`id`	The ID to use for the document. If `NULL` then Ditto will automatically assign an ID.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the inserted document, or nil if insertion failed.


                    
                    
                    -insert:writeStrategy:error:

Deprecated

use upsert(:withID:writeStrategy:error:) instead.

Inserts a new document into the collection and returns its ID.

@deprecated use upsert:writeStrategy:error: instead.

Declaration

Objective-C

- (nullable DITDocumentID *)insert:
                                (nonnull NSDictionary<NSString *, id> *)content
                     writeStrategy:(DITWriteStrategy)writeStrategy
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`writeStrategy`	Specifies the desired strategy for inserting a document.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the inserted document, or nil if insertion failed.


                    
                    
                    -insert:withID:writeStrategy:error:

Deprecated

use upsert(:withID:writeStrategy:error:) instead.

Inserts a new document into the collection and returns its ID.

@deprecated use upsert:writeStrategy:error: instead.

Declaration

Objective-C

- (nullable DITDocumentID *)insert:
                                (nonnull NSDictionary<NSString *, id> *)content
                            withID:(nullable DITDocumentID *)id
                     writeStrategy:(DITWriteStrategy)writeStrategy
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`id`	The ID to use for the document. If `NULL` then Ditto will automatically assign an ID.
`writeStrategy`	Specifies the desired strategy for inserting a document.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the inserted document, or nil if insertion failed.


                    
                    
                    -insert:isDefault:error:

Deprecated

use upsert(:writeStrategy:error:) with an equivalent DITWriteStrategy instead.

Inserts a new document into the collection and returns its ID.

@deprecated use upsert:writeStrategy:error: instead.

Declaration

Objective-C

- (nullable DITDocumentID *)insert:
                                (nonnull NSDictionary<NSString *, id> *)content
                         isDefault:(BOOL)isDefault
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`isDefault`	Whether or not the data being inserted should be treated as default data or not. Set this to `true` if you want to set a default value that you expect to be overwritten by other devices in the network. The default value is `false`.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the inserted document, or nil if insertion failed.


                    
                    
                    -insert:withID:isDefault:error:

Deprecated

use upsert(:withID:writeStrategy:error:) with an equivalent DITWriteStrategy instead.

Inserts a new document into the collection and returns its ID.

@deprecated use upsert:writeStrategy:error: instead.

Declaration

Objective-C

- (nullable DITDocumentID *)insert:
                                (nonnull NSDictionary<NSString *, id> *)content
                            withID:(nullable DITDocumentID *)id
                         isDefault:(BOOL)isDefault
                             error:(NSError *_Nullable *_Nullable)error;

Parameters

`content`	The new document to insert.
`id`	The ID to use for the document. If `NULL` then Ditto will automatically assign an ID.
`isDefault`	Whether or not the data being inserted should be treated as default data or not. Set this to `true` if you want to set a default value that you expect to be overwritten by other devices in the network. The default value is `false`.
`error`	On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.

Return Value

The ID of the inserted document, or nil if insertion failed.


                    
                    
                    -findByID:

Generates a DITPendingIDSpecificOperation with the provided document ID.

The returned object can be used to find and return the document or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about the document over time. It can also be used to update, remove or evict the document.

Declaration

Objective-C

- (nonnull DITPendingIDSpecificOperation *)findByID:
    (nonnull DITDocumentID *)docID;

Parameters


                                docID

The ID of the document.

Return Value

A DITPendingIDSpecificOperation that you can chain function calls to either get the document immediately or get updates about it over time.


                    
                    
                    -find:

Generates a DITPendingCursorOperation using the provided query.

The returned object can be used to find and return the documents or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about the list of matching documents over time. It can also be used to update, remove or evict the matching documents.

Declaration

Objective-C

- (nonnull DITPendingCursorOperation *)find:(nonnull NSString *)query;

Parameters


                                query

The query to run against the collection.

Return Value

A DITPendingCursorOperation that you can chain function calls to chain further query-related function calls.


                    
                    
                    -find:withArgs:

Generates a DITPendingCursorOperation using the provided query and query arguments.

The returned object can be used to find and return the documents or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about the list of matching documents over time. It can also be used to update, remove or evict the matching documents.

This is the recommended method to use when performing queries on a collection if you have any dynamic data included in the query string. It allows you to provide a query string with placeholders, in the form of $args.my_arg_name, along with an accompanying dictionary of arguments, in the form of { "my_arg_name": "some value" }, and the placeholders will be appropriately replaced by the matching provided arguments from the dictionary. This includes handling things like wrapping strings in quotation marks and arrays in square brackets, for example.

Declaration

Objective-C

- (nonnull DITPendingCursorOperation *)
        find:(nonnull NSString *)query
    withArgs:(nonnull NSDictionary<NSString *, id> *)queryArgs;

Parameters

`query`	The query to run against the collection.
`queryArgs`	The arguments to use to replace placeholders in the provided query.

Return Value

A DITPendingCursorOperation that you can chain function calls to chain further query-related function calls.


                    
                    
                    -findAll

Generates a DITPendingCursorOperation that relates to all documents in the collection.

The returned object can be used to find and return all of the documents in the collection or you can chain a call to observe, observeLocal, or subscribe if you want to get updates about the documents over time. It can also be used to update, remove or evict the documents.

Declaration

Objective-C

- (nonnull DITPendingCursorOperation *)findAll;

Return Value

A DITPendingCursorOperation that you can chain function calls to chain further query-related function calls.


                    
                    
                    -newAttachment:metadata:

Creates a new attachment, which can then be inserted into a document.

The file residing at the provided path will be copied into Ditto’s store. The DITAttachment object that is returned is what you can then use to insert an attachment into a document.

You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment.

Below is a snippet to show how you can use the newAttachment functionality to insert an attachment into a document.

DITAttachment *attachment = [collection newAttachment:@"/path/to/my/file.pdf"];
DITDocumentID docID = [collection insert:@{@"attachment": attachment, @"other": @"string"}];
}

Declaration

Objective-C

- (nullable DITAttachment *)
    newAttachment:(nonnull NSString *)path
         metadata:(nullable NSDictionary<NSString *, NSString *> *)metadata;

Parameters

`path`	The path to the file that you want to create an attachment with.
`metadata`	Metadata relating to the attachment.

Return Value

A DITAttachment object, which can be used to insert the attachment into a document.


                    
                    
                    -fetchAttachment:onFetchEvent:

Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report events relating to the attachment fetch attempt as it tries to download it. The onFetchEvent block may be called multiple times with progress events. It will then be called with either a DITAttachmentFetchEventCompleted event or a DITAttachmentFetchEventDeleted event. If downloading the attachment succeeds then the DITAttachmentFetchEventCompleted event that the onFetchEvent block will be called with will hold a reference to the downloaded attachment.

Declaration

Objective-C

- (nullable DITAttachmentFetcher *)
    fetchAttachment:(nonnull DITAttachmentToken *)token
       onFetchEvent:
           (nonnull void (^)(DITAttachmentFetchEvent *_Nonnull))onFetchEvent;

Parameters

`token`	The `DITAttachmentToken` relevant to the attachment that you wish to download and observe.
`onFetchEvent`	A block that will be called when there is a update to the status of the attachment fetch attempt.

Return Value

A DITAttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment’s fetch status changes. If the attachment fetcher could not be created then nil will be returned. This can happen if, for example, an invalid attachment token was provided.


                    
                    
                    -fetchAttachment:deliveryQueue:onFetchEvent:

Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report events relating to the attachment fetch attempt as it tries to download it. The onFetchEvent block may be called multiple times with progress events. It will then be called with either a DITAttachmentFetchEventCompleted event or a DITAttachmentFetchEventDeleted event. If downloading the attachment succeeds then the DITAttachmentFetchEventCompleted event that the onFetchEvent block will be called with will hold a reference to the downloaded attachment.

Declaration

Objective-C

- (nullable DITAttachmentFetcher *)
    fetchAttachment:(nonnull DITAttachmentToken *)token
      deliveryQueue:(nonnull dispatch_queue_t)dispatchQueue
       onFetchEvent:
           (nonnull void (^)(DITAttachmentFetchEvent *_Nonnull))onFetchEvent;

Parameters

`token`	The `DITAttachmentToken` relevant to the attachment that you wish to download and observe.
`dispatchQueue`	The dispatch queue that will be used when calling the provided block to deliver fetch events. You can use the version of this method that does not take a `dispatch_queue_t` argument if you want the main queue to be used.
`onFetchEvent`	A block that will be called when there is a update to the status of the attachment fetch attempt.

Return Value

A DITAttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment’s fetch status changes. If the attachment fetcher could not be created then nil will be returned. This can happen if, for example, an invalid attachment token was provided.