--- source_url: https://www.pubnub.com/docs/sdks/cocoa-objective-c/api-reference/objects title: App Context API for Cocoa Objective-C SDK updated_at: 2026-06-16T12:50:40.899Z --- > Documentation Index > For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt > For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt # App Context API for Cocoa Objective-C SDK This page describes App Context (formerly Objects v2). To upgrade from Objects v1, refer to the [migration guide](https://www.pubnub.com/docs/general/resources/migration-guides/objects-v2-migration). App Context provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use App Context to easily store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases. PubNub also triggers events when object data is changed: set, updated, or removed from the database. At the same time, making a request to set the same data that already exist, doesn't trigger any event. Clients can receive these events in real time and update their front-end application accordingly. ## User ### Get metadata for all users Returns a paginated list of UUID Metadata objects, optionally including the custom data object for each. :::warning Required keyset configuration To get all channel and user metadata, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the [Admin Portal](https://admin.pubnub.com) . ::: #### Method(s) To `Get All UUID Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)allUUIDMetadataWithRequest:(PNFetchAllUUIDMetadataRequest *)request completion:(PNFetchAllUUIDMetadataCompletionBlock)block; ``` | Parameter | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | request | PNFetchAllUUIDMetadataRequest | Yes | | `Fetch all UUID metadata` request object with all information which should be used to fetch existing `UUID metadata`. | | block | PNFetchAllUUIDMetadataCompletionBlock | Yes | | `Fetch all UUID metadata` request completion `block`. | #### PNFetchAllUUIDMetadataRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, Use `asc` or `desc` to specify sort direction | | `includeFields`Type: PNUUIDFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNUUIDTotalCountField - include how many UUID has been associated with metadata., PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests.Default value (`PNUUIDTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec PNFetchAllUUIDMetadataRequest *request = [PNFetchAllUUIDMetadataRequest new]; request.start = @""; // Add this request option, if returned metadata models should have value which has been set to // 'custom' property. request.includeFields = PNUUIDCustomField | PNUUIDTotalCountField; request.limit = 40; [self.client allUUIDMetadataWithRequest:request completion:^(PNFetchAllUUIDMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * UUID metadata successfully fetched. * Result object has following information: * result.data.metadata - List of fetched UUID metadata. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of created UUID metadata. */ } else { /** * Handle UUID metadata fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `fetch all UUID metadata` Object API is used: ```objectivec @interface PNFetchAllUUIDMetadataData : PNServiceData // List of UUID metadata objects created for current subscribe key. @property (nonatomic, readonly, strong) NSArray *metadata; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of objects created for current subscribe key. * * Value will be 0 in case if PNUUIDTotalCountField not added to 'includeFields' * of PNFetchAllUUIDMetadataRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchAllUUIDMetadataResult : PNResult // Fetch all UUID metadata request processed information. @property (nonatomic, readonly, strong) PNFetchAllUUIDMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get metadata for all users (builder pattern) :::warning Required keyset configuration To get all channel and user metadata, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the [Admin Portal](https://admin.pubnub.com) . ::: #### Method(s) ```objectivec objects() .allUUIDMetadata() .includeFields(PNUUIDFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(PNFetchAllUUIDMetadataCompletionBlock); ``` | Parameter | Description | | --- | --- | | `includeFields`Type: PNUUIDFields | `PNUUIDCustomField` - include field with additional information from `metadata` which has been used during `UUID metadata set` requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block` *Type: PNFetchAllUUIDMetadataCompletionBlock | Associated `metadata fetch` completion handler block. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().allUUIDMetadata() .start(@"") .includeFields(PNUUIDCustomField) .includeCount(YES) .limit(40) .performWithCompletion(^(PNFetchAllUUIDMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * UUID metadata successfully fetched. * Result object has following information: * result.data.metadata - List of fetched UUID metadata. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.totalCount - Total number of created UUID metadata. */ } else { /** * Handle UUID metadata fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `fetch all UUID metadata` Object API is used: ```objectivec @interface PNFetchAllUUIDMetadataData : PNServiceData // List of UUID metadata objects created for current subscribe key. @property (nonatomic, readonly, strong) NSArray *metadata; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of objects created for current subscribe key. * * Value will be 0 in case if PNUUIDTotalCountField not added to 'includeFields' * of PNFetchAllUUIDMetadataRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchAllUUIDMetadataResult : PNResult // Fetch all UUID metadata request processed information. @property (nonatomic, readonly, strong) PNFetchAllUUIDMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get user metadata Returns metadata for the specified UUID, optionally including the custom data object for each. #### Method(s) To `Get UUID Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)uuidMetadataWithRequest:(PNFetchUUIDMetadataRequest *)request completion:(PNFetchUUIDMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNFetchUUIDMetadataRequest](#pnfetchuuidmetadatarequest) | `Fetch UUID metadata` request with all information which should be used to fetch existing `UUID metadata`. | | `block` *Type: PNFetchUUIDMetadataCompletionBlock | `Fetch UUID metadata` request completion `block`. | #### PNFetchUUIDMetadataRequest | Parameter | Description | | --- | --- | | `includeFields`Type: PNUUIDFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests. Default value (`PNUUIDCustomField`) can be reset by setting 0. | | `uuid`Type: NSString | Create and configure fetch `UUID` metadata request. `uuid` - Identifier for metadata should be fetched. Will be set to current PubNub configuration uuid if nil is set. | #### Sample code ```objectivec PNFetchUUIDMetadataRequest *request = [PNFetchUUIDMetadataRequest requestWithUUID:@"uuid"]; // Add this request option, if returned metadata model should have value which has been set to // 'custom' property. request.includeFields = PNUUIDCustomField; [self.client uuidMetadataWithRequest:request completion:^(PNFetchUUIDMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * UUID metadata successfully fetched. * Fetched UUID metadata information available here: result.data.metadata */ } else { /** * Handle UUID metadata fetch error. Check 'category' property to find out possible issue * because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `fetch UUID metadata` Object API is used: ```objectivec @interface PNFetchUUIDMetadataData : PNServiceData // Requested UUID metadata object. @property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata; @end @interface PNFetchUUIDMetadataResult : PNResult // Fetch UUID metadata request processed information. @property (nonatomic, readonly, strong) PNFetchUUIDMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get user metadata (builder pattern) #### Method(s) ```objectivec objects() .uuidMetadata() .uuid(NSString *) .includeFields(PNUUIDFields) .performWithCompletion(PNFetchUUIDMetadataCompletionBlock); ``` | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Identifier for which associated `metadata` should be fetched. Default: configured PubNub client `uuid` | | `includeFields`Type: PNUUIDMFields | `PNUUIDCustomField` - include field with additional information from `metadata` which has been used during `UUID metadata set` requests. Default: `PNUUIDCustomField` *Default value can be reset by setting 0* | | `block` *Type: PNFetchUUIDMetadataCompletionBlock | `Fetch UUID metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().uuidMetadata() .uuid(@"uuid") .includeFields(PNUUIDCustomField) .performWithCompletion(^(PNFetchUUIDMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * UUID metadata successfully fetched. * Fetched UUID metadata information available here: result.data.metadata */ } else { /** * Handle UUID metadata fetch error. Check 'category' property to find out possible issue * because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `fetch UUID metadata` Object API is used: ```objectivec @interface PNFetchUUIDMetadataData : PNServiceData // Requested UUID metadata object. @property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata; @end @interface PNFetchUUIDMetadataResult : PNResult // Fetch UUID metadata request processed information. @property (nonatomic, readonly, strong) PNFetchUUIDMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Set user metadata :::warning Unsupported partial updates of custom metadata The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must: 1. Get the existing metadata and store it locally. 2. Append the new custom metadata to the existing one. 3. Set the entire updated custom object. ::: Set metadata for a UUID in the database, optionally including the custom data object for each. #### Method(s) To `Set UUID Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)setUUIDMetadataWithRequest:(PNSetUUIDMetadataRequest *)request completion:(nullable PNSetUUIDMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNSetUUIDMetadataRequest](#pnsetuuidmetadatarequest) | `Set UUID metadata` request with all information which should be associated with `UUID`. | | `block`Type: PNSetUUIDMetadataCompletionBlock | `Set UUID metadata` request completion `block`. | #### PNSetUUIDMetadataRequest | Parameter | Description | | --- | --- | | `custom`Type: NSDictionary | Additional / complex attributes which should be associated with metadata. | | `externalId`Type: NSString | Identifier from external service (database, auth service). | | `profileUrl`Type: NSString | URL at which profile available. | | `includeFields`Type: PNUUIDFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests. Default value (`PNUUIDCustomField`) can be reset by setting 0. | | `email`Type: NSString | Email address. | | `name`Type: NSString | Name which should be stored in metadata associated with specified identifier. | | `uuid`Type: NSString | Create and configure set UUID metadata request. `uuid` - Identifier with which metadata is linked. Will be set to current PubNub configuration uuid if nil is set. | :::tip API limits To learn about the maximum length of parameters used to set user metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-user-metadata). ::: #### Sample code ```objectivec PNSetUUIDMetadataRequest *request = [PNSetUUIDMetadataRequest requestWithUUID:@"uuid"]; // With this option on, returned metadata model will have value which has been set to 'custom' // property. request.includeFields = PNUUIDCustomField; request.custom = @{ @"age": @(39), @"status": @"Checking some stuff..." }; request.email = @"support@pubnub.com"; request.name = @"David"; [self.client setUUIDMetadataWithRequest:request completion:^(PNSetUUIDMetadataStatus *status) { if (!status.isError) { /** * UUID metadata successfully has been set. * UUID metadata information available here: status.data.metadata */ } else { /** * Handle UUID metadata set error. Check 'category' property to find out possible issue * because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `set UUID metadata` Object API is used: ```objectivec @interface PNSetUUIDMetadataData : PNServiceData // Updated UUID metadata object. @property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata; @end @interface PNSetUUIDMetadataStatus : PNAcknowledgmentStatus // Set UUID metadata request processed information. @property (nonatomic, readonly, strong) PNSetUUIDMetadataData *data; @end ``` ### Set user metadata (builder pattern) #### Method(s) ```objectivec objects() .setUUIDMetadata() .uuid(NSString *) .name(NSString *) .externalId(NSString *) .profileUrl(NSString *) .custom(NSDictionary *) .email(NSString *) .includeFields(PNUUIDFields) .performWithCompletion(nullable PNSetUUIDMetadataCompletionBlock); ``` :::tip API limits To learn about the maximum length of parameters used to set user metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-user-metadata). ::: | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Identifier with which new `metadata` should be associated. Default: configured PubNub client `uuid` | | `name`Type: NSString | Name which should stored in `metadata` associated with specified `UUID`. | | `externalId`Type: NSString | External identifier (database, auth service) associated with specified `UUID`. | | `profileUrl`Type: NSString | External URL with information for specified `UUID` representation. | | `custom`Type: NSDictionary | Additional information which should be stored in `metadata` associated with specified `UUID`. | | `email`Type: NSString | Email address which should be stored in `metadata` associated with specified `UUID`. | | `includeFields`Type: PNUUIDFields | `PNUUIDCustomField` - include field with additional information from `metadata` which has been used during `UUID metadata set` requests. Default: `PNUUIDCustomField` *Default value can be reset by setting 0*. | | `block`Type: PNSetUUIDMetadataCompletionBlock | `Set UUID metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().setUUIDMetadata() .uuid(@"uuid") .name(@"Serhii") .externalId(@"93FVfHUAf4RLu79J7Q3ejLVu") .profileUrl(@"https://pubnub.com") .custom(@{ @"age": @(36) }) .email(@"support@pubnub.com") .includeFields(PNUUIDCustomField) .performWithCompletion(^(PNSetUUIDMetadataStatus *status) { if (!status.isError) { /** * UUID metadata successfully has been set. * UUID metadata information available here: status.data.metadata */ } else { /** * Handle UUID metadata set error. Check 'category' property to find out possible issue * because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `set UUID metadata` Object API is used: ```objectivec @interface PNSetUUIDMetadataData : PNServiceData // Updated UUID metadata object. @property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata; @end @interface PNSetUUIDMetadataStatus : PNAcknowledgmentStatus // Set UUID metadata request processed information. @property (nonatomic, readonly, strong) PNSetUUIDMetadataData *data; @end ``` ### Remove user metadata Removes the metadata from a specified UUID. #### Method(s) To `Remove UUID Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)removeUUIDMetadataWithRequest:(PNRemoveUUIDMetadataRequest *)request completion:(nullable PNRemoveUUIDMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNRemoveUUIDMetadataRequest](#pnremoveuuidmetadatarequest) | `Remove UUID metadata` request with information about existing `metadata`. | | `block`Type: PNRemoveUUIDMetadataCompletionBlock | `Remove UUID metadata` request completion `block`. | #### PNRemoveUUIDMetadataRequest | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Create and configure delete user request. `identifier` - Create and configure remove `UUID` metadata request. Will be set to current PubNub configuration uuid if nil is set. | #### Sample code ```objectivec PNRemoveUUIDMetadataRequest *request = [PNRemoveUUIDMetadataRequest requestWithUUID:@"uuid"]; [self.client removeUUIDMetadataWithRequest:request completion:^(PNAcknowledgmentStatus *status) { if (!status.isError) { // UUID metadata successfully removed. } else { /** * Handle UUID metadata remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `remove UUID metadata` Object API is used: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNAcknowledgmentStatus : PNErrorStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Remove user metadata (builder pattern) #### Method(s) ```objectivec objects() .removeUUIDMetadata() .uuid(NSString *) .performWithCompletion(nullable PNFetchUUIDMetadataCompletionBlock); ``` | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Identifier for which associated `metadata` should be removed. Default: configured PubNub client `uuid` | | `block`Type: PNRemoveUUIDMetadataCompletionBlock | `Remove UUID metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().removeUUIDMetadata() .uuid(@"uuid") .performWithCompletion(^(PNAcknowledgmentStatus *status) { if (!status.isError) { // User successfully deleted. } else { /** * Handle user delete error. Check 'category' property to find out possible issue * because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `remove UUID metadata` Object API is used: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNAcknowledgmentStatus : PNErrorStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ## Channel ### Get metadata for all channels Returns a paginated list of Channel Metadata objects, optionally including the custom data object for each. :::warning Required keyset configuration To get all channel and user metadata, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the [Admin Portal](https://admin.pubnub.com) . ::: #### Method(s) To `Get All Channel Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)allChannelsMetadataWithRequest:(PNFetchAllChannelsMetadataRequest *)request completion:(PNFetchAllChannelsMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNFetchAllChannelsMetadataRequest](#pnfetchallchannelsmetadatarequest) | `Fetch all UUID metadata` request object with all information which should be used to fetch existing `UUID metadata`. | | `block` *Type: PNFetchAllChannelsMetadataCompletionBlock | `Fetch all UUID metadata` request completion `block`. | #### PNFetchAllChannelsMetadataRequest | Parameter | Description | | --- | --- | | `includeFields`Type: PNChannelFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelTotalCountField - include how many channels has been associated with metadata., PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests. Default value (`PNChannelTotalCountField`) can be reset by setting 0. | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec PNFetchAllChannelsMetadataRequest *request = [PNFetchAllChannelsMetadataRequest new]; request.start = @""; // Add this request option, if returned metadata models should have value which has been set to // 'custom' property. request.includeFields = PNUUIDCustomField | PNUUIDTotalCountField; request.limit = 40; [self.client allChannelsMetadataWithRequest:request completion:^(PNFetchAllChannelsMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Channels metadata successfully fetched. * Result object has following information: * result.data.metadata - List of fetched channels metadata. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of associated channel metadata. } else { /** * Handle channels metadata fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `fetch all UUID metadata` Object API is used: ```objectivec @interface PNFetchAllChannelsMetadataData : PNServiceData // List of channels metadata objects created for current subscribe key. @property (nonatomic, readonly, strong) NSArray *metadata; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of objects created for current subscribe key. * * Value will be 0 in case if PNChannelTotalCountField not added to 'includeFields' * of PNFetchAllChannelsMetadataRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchAllChannelsMetadataResult : PNResult // Fetch all channels metadata request processed information. @property (nonatomic, readonly, strong) PNFetchAllChannelsMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get metadata for all channels (builder pattern) #### Method(s) ```objectivec objects() .allChannelsMetadata() .includeFields(PNChannelFields) .includeCount(BOOL) .filter(NSString) .sort(NSArray) .limit(NSUInteger) .start(NSString) .end(NSString) .performWithCompletion(PNFetchChannelMetadataCompletionBlock); ``` | Parameter | Description | | --- | --- | | `includeFields`Type: PNChannelFields | `PNChannelCustomField` - include field with additional information from `metadata` which has been used during `channel metadata set` requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block` *Type: PNFetchAllChannelsMetadataCompletionBlock | `Fetch all UUID metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().allChannelsMetadata() .start(@"") .includeFields(PNChannelCustomField) .includeCount(YES) .limit(40) .performWithCompletion(^(PNFetchAllChannelsMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Channels metadata successfully fetched. * Result object has following information: * result.data.metadata - List of fetched channels metadata. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of associated channel metadata. } else { /** * Handle channels metadata fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `fetch all UUID metadata` Object API is used: ```objectivec @interface PNFetchAllChannelsMetadataData : PNServiceData // List of channels metadata objects created for current subscribe key. @property (nonatomic, readonly, strong) NSArray *metadata; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of objects created for current subscribe key. * * Value will be 0 in case if PNChannelTotalCountField not added to 'includeFields' * of PNFetchAllChannelsMetadataRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchAllChannelsMetadataResult : PNResult // Fetch all channels metadata request processed information. @property (nonatomic, readonly, strong) PNFetchAllChannelsMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get channel metadata Returns metadata for the specified Channel, optionally including the custom data object for each. #### Method(s) To `Get Channel Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)channelMetadataWithRequest:(PNFetchChannelMetadataRequest *)request completion:(PNFetchChannelMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNFetchChannelMetadataRequest](#pnfetchchannelmetadatarequest) | `Fetch channel metadata` request with all information which should be used to fetch existing `channel metadata`. | | `block` *Type: PNFetchChannelMetadataCompletionBlock | `Fetch channel metadata` request completion `block`. | #### PNFetchChannelMetadataRequest | Parameter | Description | | --- | --- | | `includeFields`Type: PNChannelFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests. Default value (`PNChannelCustomField`) can be reset by setting 0. | | `channel`Type: NSString | Create and configure fetch channel metadata request. `channel` - Name of channel for which metadata should be fetched. | #### Sample code ```objectivec PNFetchChannelMetadataRequest *request = [PNFetchChannelMetadataRequest requestWithChannel:@"channel"]; // Add this request option, if returned metadata model should have value which has been set to // 'custom' property. request.includeFields = PNChannelCustomField; [self.client channelMetadataWithRequest:request completion:^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Channel metadata successfully fetched. * Channel metadata information available here: result.data.metadata */ } else { /** * Handle channel metadata fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `fetch channel metadata` Object API is used: ```objectivec @interface PNFetchChannelMetadataData : PNServiceData // Requested channel metadata object. @property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata; @end @interface PNFetchChannelsMetadataResult : PNResult // Fetch channel metadata request processed information. @property (nonatomic, readonly, strong) PNFetchChannelMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get channel metadata (builder pattern) #### Method(s) ```objectivec objects() .channelMetadata(NSString *) .includeFields(PNChannelFields) .performWithCompletion(PNFetchChannelMetadataCompletionBlock); ``` | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel for which associated `metadata` should be fetched. | | `includeFields`Type: NSString | `PNChannelCustomField` - include field with additional information from `metadata` which has been used during `channel metadata set` requests. Default: `PNChannelCustomField` *Default value can be reset by setting 0* | | `block` *Type: PNFetchChannelMetadataCompletionBlock | `Fetch channel metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().channelMetadata(@"channel") .includeFields(PNChannelCustomField) .performWithCompletion(^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Channel metadata successfully fetched. * Channel metadata information available here: result.data.metadata */ } else { /** * Handle channel metadata fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `fetch channel metadata` Object API is used: ```objectivec @interface PNFetchChannelMetadataData : PNServiceData // Requested channel metadata object. @property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata; @end @interface PNFetchChannelsMetadataResult : PNResult // Fetch channel metadata request processed information. @property (nonatomic, readonly, strong) PNFetchChannelMetadataData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Set channel metadata :::warning Unsupported partial updates of custom metadata The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must: 1. Get the existing metadata and store it locally. 2. Append the new custom metadata to the existing one. 3. Set the entire updated custom object. ::: Set metadata for a Channel in the database, optionally including the custom data object for each. #### Method(s) To `Set Channel Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)setChannelMetadataWithRequest:(PNSetChannelMetadataRequest *)request completion:(nullable PNSetChannelMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNSetChannelMetadataRequest](#pnsetchannelmetadatarequest) | `Set channel metadata` request with all information which should be associated with `channel`. | | `block`Type: PNSetChannelMetadataCompletionBlock | `Set channel metadata` request completion `block`. | #### PNSetChannelMetadataRequest | Parameter | Description | | --- | --- | | `custom`Type: NSDictionary | Additional / complex attributes which should be stored in metadata associated with specified channel. [App Context filtering language](https://www.pubnub.com/docs/general/metadata/filtering) doesn’t support filtering by custom properties. | | `information`Type: NSString | Description which should be stored in metadata associated with specified channel. | | `includeFields`Type: PNChannelFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests. Default value (`PNChannelCustomField`) can be reset by setting 0. | | `name`Type: NSString | Name which should be stored in metadata associated with specified channel. | | `channel`Type: NSString | Create and configure set channel metadata request. `channel` - Name of channel for which metadata should be set. | :::tip API limits To learn about the maximum length of parameters used to set channel metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-channel-metadata). ::: #### Sample code ```objectivec PNSetChannelMetadataRequest *request = [PNSetChannelMetadataRequest requestWithChannel:@"channel"]; // Add this request option, if returned metadata model should have value which has been set to // 'custom' property. request.includeFields = PNChannelCustomField; request.custom = @{ @"responsibilities": @"Manage tests", @"status": @"offline" }; request.name = @"Updated channel name"; [self.client setChannelMetadataWithRequest:request completion:^(PNSetChannelMetadataStatus *status) { if (!status.isError) { /** * Channel metadata successfully has been set. * Channel metadata information available here: status.data.metadata */ } else { /** * Handle channel metadata update error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `set channel metadata` Object API is used: ```objectivec @interface PNSetChannelMetadataData : PNServiceData // Associated channel's metadata object. @property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata; @end @interface PNSetChannelMetadataStatus : PNAcknowledgmentStatus // Set channel metadata request processed information. @property (nonatomic, readonly, strong) PNSetChannelMetadataData *data; @end ``` #### Other examples ##### Iteratively update existing metadata ```objectivec #import #import void showHelp() { printf("\tTo exit type '/exit'\n\tTo show the current object type '/show'\n\tTo show this help type '/help'\n\n"); } int main(int argc, const char *argv[]) { @autoreleasepool { PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo" subscribeKey:@"demo"]; configuration.uuid = @"example"; PubNub *pubnub = [PubNub clientWithConfiguration:configuration]; NSString *channel = @"demo_example"; showHelp(); printf("We're setting the channel's %s additional info.\n", [channel UTF8String]); char inputBuffer[256]; printf("Enter the channel name: "); fgets(inputBuffer, 256, stdin); NSString *name = [NSString stringWithUTF8String:inputBuffer].stringByTrimmingCharactersInSet([NSCharacterSet newlineCharacterSet]); printf("Enter the channel description: "); fgets(inputBuffer, 256, stdin); NSString *description = [NSString stringWithUTF8String:inputBuffer].stringByTrimmingCharactersInSet([NSCharacterSet newlineCharacterSet]); // Set basic channel info [pubnub.objects().setChannelMetadata(channel) .name(name) .information(description) .includeFields(PNChannelCustomField) .performWithCompletion(^(PNSetChannelMetadataStatus *status) { if (!status.isError) { printf("The channel has been created with name and description.\n"); } else { printf("Error setting channel metadata: %s\n", [status.errorData.information UTF8String]); } })]; while (true) { printf("Enter the field name: "); fgets(inputBuffer, 256, stdin); NSString *fieldName = [NSString stringWithUTF8String:inputBuffer].stringByTrimmingCharactersInSet([NSCharacterSet newlineCharacterSet]); if ([fieldName isEqualToString:@"/exit"]) { break; } else if ([fieldName isEqualToString:@"/show"]) { [pubnub.objects().channelMetadata(channel) .includeFields(PNChannelCustomField) .performWithCompletion(^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { printf("%s\n", [[result.data.metadata description] UTF8String]); } else { printf("Error fetching channel metadata: %s\n", [status.errorData.information UTF8String]); } })]; continue; } else if ([fieldName isEqualToString:@"/help"]) { showHelp(); continue; } printf("Enter the field value: "); fgets(inputBuffer, 256, stdin); NSString *fieldValue = [NSString stringWithUTF8String:inputBuffer].stringByTrimmingCharactersInSet([NSCharacterSet newlineCharacterSet]); [pubnub.objects().channelMetadata(channel) .includeFields(PNChannelCustomField) .performWithCompletion(^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) { if (!status.isError) { NSMutableDictionary *customFields = [(result.data.metadata.custom ?: @{}) mutableCopy]; NSString *existingValue = customFields[fieldName]; if (existingValue) { printf("Field %s already has a value. Overwrite? (y/n): ", [fieldName UTF8String]); fgets(inputBuffer, 256, stdin); NSString *confirmation = [NSString stringWithUTF8String:inputBuffer].stringByTrimmingCharactersInSet([NSCharacterSet newlineCharacterSet]); if ([confirmation.lowercaseString isEqualToString:@"n"]) { printf("Object will not be updated.\n"); return; } } // Update the custom field value customFields[fieldName] = fieldValue; // Update the metadata [pubnub.objects().setChannelMetadata(channel) .name(result.data.metadata.name) .information(result.data.metadata.information) .custom(customFields) .includeFields(PNChannelCustomField) .performWithCompletion(^(PNSetChannelMetadataStatus *status) { if (!status.isError) { printf("Object has been updated.\n"); } else { printf("Error setting channel metadata: %s\n", [status.errorData.information UTF8String]); } })]; } else { printf("Error fetching channel metadata: %s\n", [status.errorData.information UTF8String]); } })]; } } return 0; } ``` ### Set channel metadata (builder pattern) :::warning Unsupported partial updates of custom metadata The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must: 1. Get the existing metadata and store it locally. 2. Append the new custom metadata to the existing one. 3. Set the entire updated custom object. ::: #### Method(s) ```objectivec objects() .setChannelMetadata(NSString *) .includeFields(PNChannelFields) .channel(NSString) .name(NSString) .information(NSString) .custom(NSDictionary) .performWithCompletion(nullable PNFetchChannelMetadataCompletionBlock); ``` :::tip API limits To learn about the maximum length of parameters used to set channel metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-channel-metadata). ::: | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel with which new `metadata` should be associated. | | `name`Type: NSString | Name which should stored in `metadata` associated with specified `channel`. | | `information`Type: NSString | Description which should be stored in `metadata` associated with specified `channel`. | | `custom`Type: NSDictionary | Additional information which should be stored in `metadata` associated with specified `channel`. [App Context filtering language](https://www.pubnub.com/docs/general/metadata/filtering) doesn’t support filtering by custom properties. | | `includeFields`Type: PNChannelFields | `PNChannelCustomField` - include field with additional information from `metadata` which has been used during `channel metadata set` requests. Default: `PNChannelCustomField` *Default value can be reset by setting 0*. | | `block`Type: PNSetChannelMetadataCompletionBlock | `Set channel metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().setChannelMetadata(@"channel") .name(@"Admin") .information(@"Administrative channel") .custom(@{ @"responsibilities": @"Manage access to protected resources" }) .includeFields(PNChannelCustomField) .performWithCompletion(^(PNSetChannelMetadataStatus *status) { if (!status.isError) { /** * Channel metadata successfully has been set. * Channel metadata information available here: status.data.metadata */ } else { /** * Handle channel metadata update error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `set channel metadata` Object API is used: ```objectivec @interface PNSetChannelMetadataData : PNServiceData // Associated channel's metadata object. @property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata; @end @interface PNSetChannelMetadataStatus : PNAcknowledgmentStatus // Set channel metadata request processed information. @property (nonatomic, readonly, strong) PNSetChannelMetadataData *data; @end ``` ### Remove channel metadata Removes the metadata from a specified channel. #### Method(s) To `Remove Channel Metadata` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)removeChannelMetadataWithRequest:(PNRemoveChannelMetadataRequest *)request completion:(nullable PNRemoveChannelMetadataCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNRemoveChannelMetadataRequest](#pnremovechannelmetadatarequest) | `Remove channel metadata` request with information about existing metadata. | | `block`Type: PNRemoveChannelMetadataCompletionBlock | `Remove channel metadata` request completion `block`. | #### PNRemoveChannelMetadataRequest | Parameter | Description | | --- | --- | | `channel`Type: NSString | Create and configure remove channel metadata request. `channel` - Name of channel for which metadata should be removed. | #### Sample code ```objectivec PNRemoveChannelMetadataRequest *request = [PNRemoveChannelMetadataRequest requestWithChannel:@"channel"]; [self.client removeChannelMetadataWithRequest:request completion:^(PNAcknowledgmentStatus *status) { if (!status.isError) { // Channel metadata successfully removed. } else { /** * Handle channel metadata remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `remove channel metadata` Object API is used: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNAcknowledgmentStatus : PNErrorStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Remove channel metadata (builder pattern) #### Method(s) ```objectivec objects() .removeChannelMetadata(NSString *) .performWithCompletion(nullable PNRemoveChannelMetadataCompletionBlock); ``` | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel for which associated `metadata` should be removed. | | `block`Type: PNRemoveChannelMetadataCompletionBlock | `Remove channel metadata` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().removeChannelMetadata(@"channel") .performWithCompletion(^(PNAcknowledgmentStatus *status) { if (!status.isError) { // Channel metadata successfully removed. } else { /** * Handle channel metadata remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `remove channel metadata` Object API is used: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNAcknowledgmentStatus : PNErrorStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ## Channel memberships ### Get channel memberships The method returns a list of channel memberships for a user. This method doesn't return a user's subscriptions. #### Method(s) To `Get Memberships` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)membershipsWithRequest:(PNFetchMembershipsRequest *)request completion:(PNFetchMembershipsCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNFetchMembershipsRequest](#pnfetchmembershipsrequest) | `Fetch UUID's memberships` request with all information which should be used to fetch existing `UUID's memberships`. | | `block` *Type: PNFetchMembershipsCompletionBlock | `Fetch UUID's memberships` request completion `block`. | #### PNFetchMembershipsRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction. | | `includeFields`Type: NSArray`` | Bitfield set to fields which should be returned with response. **Supported fields:** PNMembershipsTotalCountField - include how many memberships UUID has., PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. Default value (`PNMembershipsTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of members to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec PNFetchMembershipsRequest *request = [PNFetchMembershipsRequest requestWithUUID:@"uuid"]; request.start = @""; // Add this request option, if returned membership models should have value which has been set to // 'custom' and 'channel' properties. request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField; request.limit = 40; [self.client membershipsWithRequest:request completion:^(PNFetchMembershipsResult *result, PNErrorStatus *status) { if (!status.isError) { /** * UUID's memberships successfully fetched. * Result object has following information: * result.data.memberships - List of UUID's memberships. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `fetch memberships` Object API is used: ```objectivec @interface PNFetchMembershipsData : PNServiceData // List of fetched memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of members created for current subscribe key. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchMembershipsResult : PNAcknowledgmentStatus // Fetch memberships request processed information. @property (nonatomic, readonly, strong) PNFetchMembershipsData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get channel memberships (builder pattern) #### Method(s) ```objectivec objects() .memberships() .uuid(NSString *) .includeFields(PNMembershipFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(PNFetchMembershipsCompletionBlock); ``` | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Name of channel from which members should be fetched. | | `includeFields`Type: PNMembershipFields | PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block` *Type: PNFetchMembershipsCompletionBlock | `Fetch UUID's memberships` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().memberships() .uuid(@"uuid") .includeCount(YES) .limit(40) .includeFields(PNMembershipCustomField | PNMembershipChannelField) .performWithCompletion(^(PNFetchMembershipsResult *result, PNErrorStatus *status) { if (!status.isError) { /** * UUID's memberships successfully fetched. * Result object has following information: * result.data.memberships - List of UUID's memberships. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `fetch memberships` Object API is used: ```objectivec @interface PNFetchMembershipsData : PNServiceData // List of fetched memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of members created for current subscribe key. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchMembershipsResult : PNAcknowledgmentStatus // Fetch memberships request processed information. @property (nonatomic, readonly, strong) PNFetchMembershipsData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Set channel memberships Set channel memberships for a UUID. #### Method(s) To `Set Memberships` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)setMembershipsWithRequest:(PNSetMembershipsRequest *)request completion:(nullable PNManageMembershipsCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNSetMembershipsRequest](#pnsetmembershipsrequest) | `Set UUID's memberships` request with information which should be used to set `channels` membership. | | `block`Type: PNManageMembershipsCompletionBlock | `Set UUID's memberships` request completion `block`. | #### PNSetMembershipsRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction. | | `includeFields`Type: PNMembershipFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNMembershipsTotalCountField - include how many memberships UUID has., PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. Default value (`PNMembershipsTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | :::tip API limits To learn about the maximum length of parameters used to set channel membership metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-membership-metadata). ::: #### Sample code ```objectivec NSArray *channels = @[ @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } } ]; PNSetMembershipsRequest *request = [PNSetMembershipsRequest requestWithUUID:@"uuid" channels:channels]; // Add this request option, if returned membership models should have value which has been set to // 'custom' and 'channel' properties. request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField; request.limit = 40; [self.client setMembershipsWithRequest:request completion:^(PNManageMembershipsStatus *status) { if (!status.isError) { /** * UUID's memberships successfully set. * Result object has following information: * status.data.memberships - List of UUID's existing memberships. * status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * status.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships set error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `set memberships` Object API is used: ```objectivec @interface PNManageMembershipsData : PNServiceData // List of existing memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageMembershipsStatus : PNAcknowledgmentStatus // Memberships set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageMembershipsData *data; @end ``` ### Set channel memberships (builder pattern) #### Method(s) ```objectivec objects() .setMemberships() .uuid(NSString *) .channels(NSArray *) .includeFields(PNMembershipFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(nullable PNManageMembershipsCompletionBlock); ``` :::tip API limits To learn about the maximum length of parameters used to set channel membership metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-membership-metadata). ::: | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Identifier for which memberships should be set. Default: configured PubNub client `uuid` | | `channels`Type: NSArray | List of `channels` for which `metadata` associated with each of them in context of `UUID` should be set. Each entry is dictionary with `channel` and `optional` `custom` fields. `custom` should be dictionary with simple objects: `NSString` and `NSNumber`. | | `includeFields`Type: PNMembershipFields | PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block`Type: PNManageMembershipsCompletionBlock | `Set UUID's memberships` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec NSArray *channels = @[ @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } } ]; self.client.objects().setMemberships() .uuid(@"uuid") .channels(channels) .includeCount(YES) .limit(40) .includeFields(NMembershipCustomField | PNMembershipChannelField) .performWithCompletion(^(PNManageMembershipsStatus *status) { if (!status.isError) { /** * UUID's memberships successfully set. * Result object has following information: * status.data.memberships - List of UUID's existing memberships. * status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * status.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships set error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `set memberships` Object API is used: ```objectivec @interface PNManageMembershipsData : PNServiceData // List of existing memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageMembershipsStatus : PNAcknowledgmentStatus // Memberships set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageMembershipsData *data; @end ``` ### Remove channel memberships Remove channel memberships for a UUID. #### Method(s) To `Remove Memberships` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)removeMembershipsWithRequest:(PNRemoveMembershipsRequest *)request completion:(nullable PNManageMembershipsCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNRemoveMembershipsRequest](#pnremovemembershipsrequest) | `Remove UUID's memberships` request with information which should be used to remove `channels` membership. | | `block`Type: PNManageMembershipsCompletionBlock | `Remove UUID's memberships` request completion block. | #### PNRemoveMembershipsRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction. | | `includeFields`Type: PNMembershipFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNMembershipsTotalCountField - include how many memberships UUID has., PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. Default value (`PNMembershipsTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec NSArray *channels = @[@"channel1", @"channel2"]; PNRemoveMembershipsRequest *request = [PNRemoveMembershipsRequest requestWithUUID:@"uuid" channels:channels]; // Add this request option, if returned membership models should have value which has been set to // 'custom' and 'channel' properties. request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField; request.limit = 40; [self.client removeMembershipsWithRequest:request completion:^(PNManageMembershipsStatus *status) { if (!status.isError) { /** * UUID's memberships successfully removed. * Result object has following information: * status.data.memberships - List of UUID's existing memberships. * status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * status.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `remove memberships` Object API is used: ```objectivec @interface PNManageMembershipsData : PNServiceData // List of existing memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageMembershipsStatus : PNAcknowledgmentStatus // Memberships set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageMembershipsData *data; @end ``` ### Remove channel memberships (builder pattern) #### Method(s) ```objectivec objects() .removeMemberships() .uuid(NSString *) .channels(NSArray *) .includeFields(PNMemberFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(nullable PNManageMembershipsCompletionBlock); ``` | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Identifier for which memberships should be removed. Default: configured PubNub client `uuid` | | `channels`Type: NSArray | List of `channels` from which `UUID` should be removed as `member`. | | `includeFields`Type: PNMembershipFields | PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. | | `includeCount`Type: BOOL | Whether total count of `members` should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block`Type: PNManageMembershipsCompletionBlock | `Remove UUID's memberships` request completion block. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().removeMemberships() .uuid(@"uuid") .channels(@[@"channel1", @"channel2"]) .includeCount(YES) .limit(40) .includeFields(PNMembershipCustomField | PNMembershipChannelField) .performWithCompletion(^(PNManageMembershipsStatus *status) { if (!status.isError) { /** * UUID's memberships successfully removed. * Result object has following information: * status.data.memberships - List of UUID's existing memberships. * status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * status.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `remove memberships` Object API is used: ```objectivec @interface PNManageMembershipsData : PNServiceData // List of existing memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageMembershipsStatus : PNAcknowledgmentStatus // Memberships set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageMembershipsData *data; @end ``` ### Manage channel memberships The method Set and Remove channel memberships for a user. #### Method(s) To `Manage Memberships` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)manageMembershipsWithRequest:(PNManageMembershipsRequest *)request completion:(nullable PNManageMembershipsCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNManageMembershipsRequest](#pnmanagemembershipsrequest) | `Manage UUID's memberships` request with information what modifications to `UUID's memberships` should be done (`set` / `remove` `channels`). | | `block`Type: PNManageMembershipsCompletionBlock | `Manage UUID's memberships` request completion `block`. | #### PNManageMembershipsRequest | Parameter | Description | | --- | --- | | `setChannels`Type: NSArray`` | List of channels within which UUID should be set as member. Each entry is dictionary with channel and optional `custom` fields. `custom` should be dictionary with simple objects: NSString and NSNumber. | | `removeChannels`Type: NSArray`` | List of channels from which UUID should be removed as member. | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (ascending used by default) or `:desc` (descending) to field name. | | `includeFields`Type: PNMembershipFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNMembershipsTotalCountField - include how many memberships UUID has., PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. Default value (`PNMembershipsTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec PNManageMembershipsRequest *request = [PNManageMembershipsRequest requestWithUUID:@"uuid"]; request.setChannels = @[ @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } } ]; request.removeChannels = @[@"channel3", @"channel4"]; // Add this request option, if returned membership models should have value which has been set to // 'custom' and 'channel' properties. request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField; request.limit = 40; [self.client manageMembershipsWithRequest:request completion:^(PNManageMembershipsStatus *status) { if (!status.isError) { /** * UUID's memberships successfully set. * Result object has following information: * status.data.memberships - List of UUID's existing memberships. * status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * status.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships set error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `manage memberships` Object API is used: ```objectivec @interface PNManageMembershipsData : PNServiceData // List of existing memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageMembershipsStatus : PNAcknowledgmentStatus // Memberships set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageMembershipsData *data; @end ``` ### Manage channel memberships (builder pattern) #### Method(s) ```objectivec objects() .manageMemberships() .uuid(NSString *) .set(NSArray *) .remove(NSArray *) .includeFields(PNMemberFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(nullable PNManageMembershipsCompletionBlock); ``` | Parameter | Description | | --- | --- | | `uuid`Type: NSString | Identifier for which memberships should be set. Default: configured PubNub client `uuid` | | `set`Type: NSArray | List of `channels` for which `metadata` associated with each of them in context of `UUID` should be set. Each entry is dictionary with `channel` and `optional` `custom` fields. `custom` should be dictionary with simple objects: `NSString` and `NSNumber`. | | `remove`Type: NSArray | List of `channels` from which `UUID` should be removed as `member`. | | `includeFields`Type: PNMembershipFields | PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests., PNMembershipChannelField - include channel's metadata into response (not only name)., PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block`Type: PNManageMembershipsCompletionBlock | `Manage UUID's memberships` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec NSArray *setChannels = @[ @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } } ]; NSArray *removeChannels = @[@"channel3", @"channel4"]; self.client.objects().manageMemberships() .uuid(@"uuid") .set(setChannels) .remove(removeChannels) .includeCount(YES) .limit(40) .includeFields(PNMembershipCustomField | PNMembershipChannelField) .performWithCompletion(^(PNManageMembershipsStatus *status) { if (!status.isError) { /** * UUID's memberships successfully set. * Result object has following information: * status.data.memberships - List of UUID's existing memberships. * status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * status.data.totalCount - Total number of UUID's memberships. */ } else { /** * Handle UUID's memberships set error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `manage memberships` Object API is used: ```objectivec @interface PNManageMembershipsData : PNServiceData // List of existing memberships. @property (nonatomic, readonly, strong) NSArray *memberships; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields' * of PNSetMembershipsRequest / PNRemoveMembershipsRequest / PNManageMembershipsRequest or * PNFetchMembershipsRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageMembershipsStatus : PNAcknowledgmentStatus // Memberships set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageMembershipsData *data; @end ``` ## Channel members ### Get channel members The method returns a list of members in a channel. The list will include user metadata for members that have additional metadata stored in the database. #### Method(s) To `Get Channel Members` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)channelMembersWithRequest:(PNFetchChannelMembersRequest *)request completion:(PNFetchChannelMembersCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNFetchChannelMembersRequest](#pnfetchchannelmembersrequest) | `Fetch channel's members` request with all information which should be used to fetch existing `channel's members`. | | `block` *Type: PNFetchChannelMembersCompletionBlock | `Fetch channel's members` request completion block. | #### PNFetchChannelMembersRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction. | | `includeFields`Type: PNChannelMemberFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelMembersTotalCountField - include how many members channel has., PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. Default value (`PNChannelMembersTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of members to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec PNFetchChannelMembersRequest *request = [PNFetchChannelMembersRequest requestWithChannel:@"channel"]; request.start = @""; // Add this request option, if returned member models should have value which has been set to // 'custom' and 'uuid' properties. request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField; request.limit = 40; [self.client channelMembersWithRequest:request completion:^(PNFetchChannelMembersResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Channel's members successfully fetched. * Result object has following information: * result.data.members - List of channel's members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `fetch members` Object API is used: ```objectivec @interface PNFetchChannelMembersData : PNServiceData // List of fetched members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of members created for current subscribe key. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchChannelMembersResult : PNAcknowledgmentStatus // Fetch members request processed information. @property (nonatomic, readonly, strong) PNFetchChannelMembersData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Get channel members (builder pattern) #### Method(s) ```objectivec objects() .channelMembers(NSString *) .includeFields(PNChannelMemberFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(PNFetchChannelMembersCompletionBlock); ``` | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel from which members should be fetched. | | `includeFields`Type: PNChannelMemberFields | PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block` *Type: PNFetchChannelMembersCompletionBlock | `Fetch channel's members` request completion block. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().channelMembers(@"channel") .includeCount(YES) .limit(40) .includeFields(PNChannelMemberCustomField | PNChannelMemberUUIDField) .performWithCompletion(^(PNFetchChannelMembersResult *result, PNErrorStatus *status) { if (!status.isError) { /** * Channel's members successfully fetched. * Result object has following information: * result.data.members - List of channel's members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members fetch error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `fetch members` Object API is used: ```objectivec @interface PNFetchChannelMembersData : PNServiceData // List of fetched members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of members created for current subscribe key. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNFetchChannelMembersResult : PNAcknowledgmentStatus // Fetch members request processed information. @property (nonatomic, readonly, strong) PNFetchChannelMembersData *data; @end ``` Error response which is used in case of App Context API call failure: ```objectivec @interface PNErrorData : PNServiceData // Stringified error information. @property (nonatomic, readonly, strong) NSString *information; @end @interface PNErrorStatus : PNStatus // Whether status object represent error or not. @property (nonatomic, readonly, assign, getter = isError) BOOL error; // Additional information related to error status object. @property (nonatomic, readonly, strong) PNErrorData *errorData; @end ``` ### Set channel members This method sets members in a channel. #### Method(s) To `Set Channel Members` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)setChannelMembersWithRequest:(PNSetChannelMembersRequest *)request completion:(nullable PNManageChannelMembersCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNSetChannelMembersRequest](#pnsetmembersrequest) | `Set channel's members` list request with information which should be used to set `UUID` member. | | `block`Type: PNManageChannelMembersCompletionBlock | `Set channel's members` list request completion `block`. | #### PNSetMembersRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction. | | `includeFields`Type: PNChannelMemberFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelMembersTotalCountField - include how many members channel has., PNChannelMemberCustomField - field with additional information from metadata which has been associated with UUID during channel member set requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. Default value (`PNChannelMembersTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | :::tip API limits To learn about the maximum length of parameters used to set channel members metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-channel-members-metadata). ::: #### Sample code ```objectivec NSArray>NSDictionary *> *uuids = @[ @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } } ]; PNSetChannelMembersRequest *request = [PNSetChannelMembersRequest requestWithChannel:@"channel" uuids:uuids]; // Add this request option, if returned member models should have value which has been set to // 'custom' and 'uuid' properties. request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField; request.limit = 40; [self.client setChannelMembersWithRequest:request completion:^(PNManageChannelMembersStatus *status) { if (!status.isError) { /** * Channel's members successfully set. * Result object has following information: * result.data.members - List of existing channel's members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members set error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `set members` Object API is used: ```objectivec @interface PNManageChannelMembersData : PNServiceData // List of existing members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageChannelMembersStatus : PNAcknowledgmentStatus // Members set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageChannelMembersData *data; @end ``` ### Set channel members (builder pattern) #### Method(s) ```objectivec objects() .setChannelMembers(NSString *) .uuids(NSArray *) .includeFields(PNChannelMemberFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(nullable PNManageChannelMembersCompletionBlock); ``` :::tip API limits To learn about the maximum length of parameters used to set channel members metadata, refer to [REST API docs](https://www.pubnub.com/docs/sdks/rest-api/set-channel-members-metadata). ::: | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel from which members should be set. | | `uuids`Type: NSArray | List of `UUIDs` for which `metadata` associated with each of them in context of `channel` should be set. Each entry is dictionary with `UUID` and `optional` `custom` fields. `custom` should be dictionary with simple objects: `NSString` and `NSNumber`. | | `includeFields`Type: PNChannelMemberFields | PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member set requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. Only objects whose properties satisfy the given expression are returned. For more details on the supported grammar, check [this](https://www.pubnub.com/docs/general/metadata/filtering) | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block`Type: PNManageChannelMembersCompletionBlock | `Set channel's members` list request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec NSArray *uuids = @[ @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } } ]; self.client.objects().setChannelMembers(@"channel") .uuids(uuids) .includeCount(YES) .limit(40) .includeFields(PNChannelMemberCustomField | PNChannelMemberUserField) .performWithCompletion(^(PNManageChannelMembersStatus *status) { if (!status.isError) { /** * Channel's members successfully set. * Result object has following information: * result.data.members - List of existing channel's members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members set error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `set members` Object API is used: ```objectivec @interface PNManageChannelMembersData : PNServiceData // List of existing members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageChannelMembersStatus : PNAcknowledgmentStatus // Members set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageChannelMembersData *data; @end ``` ### Remove channel members Remove members from a Channel. #### Method(s) To `Remove Channel Members` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)removeChannelMembersWithRequest:(PNRemoveChannelMembersRequest *)request completion:(nullable PNManageChannelMembersCompletionBlock) ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNRemoveChannelMembersRequest](#pnremovechannelmembersrequest) | `Remove channel's members` request with information which should be used to remove `UUID` members. | | `block`Type: PNManageChannelMembersCompletionBlock | `Remove channel's members` request completion `block`. | #### PNRemoveChannelMembersRequest | Parameter | Description | | --- | --- | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. Use `asc` or `desc` to specify sort direction. | | `includeFields`Type: PNChannelMemberFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelMembersTotalCountField - include how many members channel has., PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. Default value (`PNChannelMembersTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec NSArray *uuids = @[@"uuid3", @"uuid4"]; PNRemoveChannelMembersRequest *request = [PNRemoveChannelMembersRequest requestWithChannel:@"channel" uuids:uuids]; // Add this request option, if returned member models should have value which has been set to // 'custom' and 'uuid' properties. request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField; request.limit = 40; [self.client removeChannelMembersWithRequest:request completion:^(PNManageChannelMembersStatus *status) { if (!status.isError) { /** * Channel's members successfully removed. * Result object has following information: * result.data.members - List of channel's existing members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `remove members` Object API is used: ```objectivec @interface PNManageChannelMembersData : PNServiceData // List of existing members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageChannelMembersStatus : PNAcknowledgmentStatus // Members set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageChannelMembersData *data; @end ``` ### Remove channel members (builder pattern) #### Method(s) ```objectivec objects() .removeChannelMembers(NSString *) .uuids(NSArray *) .includeFields(PNChannelMemberFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(nullable PNManageChannelMembersCompletionBlock); ``` | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel from which members should be removed. | | `uuids`Type: NSArray | List of `UUIDs` which should be removed from `channel's` list. | | `includeFields`Type: PNChannelMemberFields | PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. | | `includeCount`Type: BOOL | Whether total count of `members` should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block`Type: PNManageChannelMembersCompletionBlock | `Remove channel's members` request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec self.client.objects().removeChannelMembers(@"channel") .uuids(@[@"uuid3", @"uuid4"]) .includeCount(YES) .limit(40) .includeFields(PNChannelMemberCustomField | PNChannelMemberUserField) .performWithCompletion(^(PNManageChannelMembersStatus *status) { if (!status.isError) { /** * Channel's members successfully removed. * Result object has following information: * result.data.members - List of channel's existing members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members remove error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `remove members` Object API is used: ```objectivec @interface PNManageChannelMembersData : PNServiceData // List of existing members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageChannelMembersStatus : PNAcknowledgmentStatus // Members set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageChannelMembersData *data; @end ``` ### Manage channel members The method Set and Remove channel memberships for a user. #### Method(s) To `Manage Channel Members` you can use the following method(s) in the Cocoa SDK: ```objectivec - (void)manageChannelMembersWithRequest:(PNManageChannelMembersRequest *)request completion:(nullable PNManageChannelMembersCompletionBlock)block; ``` | Parameter | Description | | --- | --- | | `request` *Type: [PNManageChannelMembersRequest](#pnmanagechannelmembersrequest) | `Manage channel's members` list request with information what modifications to `channel's` members list should be done (`set` / `remove` `UUID`). | | `block`Type: PNManageChannelMembersCompletionBlock | `Manage channel's members` list request completion `block`. | #### PNManageChannelMembersRequest | Parameter | Description | | --- | --- | | `setMembers`Type: NSArray`` | List of UUIDs which should be added to channel's members list. Each entry is dictionary with uuid and optional `custom` fields. `custom` should be dictionary with simple objects: NSString and NSNumber. | | `removeMembers`Type: NSArray`` | BList of UUIDs which should be removed from channel's list. | | `sort`Type: NSArray`` | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (ascending used by default) or `:desc` (descending) to field name. | | `includeFields`Type: PNChannelMemberFields | Bitfield set to fields which should be returned with response. **Supported fields:** PNChannelMembersTotalCountField - include how many members channel has., PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. Default value (`PNChannelMembersTotalCountField`) can be reset by setting 0. | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `limit`Type: NSUInteger | Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified. | #### Sample code ```objectivec PNManageChannelMembersRequest *request = [PNManageChannelMembersRequest requestWithChannel:@"channel"]; request.setMembers = @[ @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } } ]; request.removeMembers = @[@"uuid3", @"uuid4"]; // Add this request option, if returned member models should have value which has been set to // 'custom' and 'uuid' properties. request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField; request.limit = 40; [self.client manageChannelMembersWithRequest:request completion:^(PNManageChannelMembersStatus *status) { if (!status.isError) { /** * Channel's members successfully changed. * Result object has following information: * result.data.members - List of existing channel's members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members manage error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }]; ``` #### Response Response objects which is returned by client when `manage members` Object API is used: ```objectivec @interface PNManageChannelMembersData : PNServiceData // List of existing members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageChannelMembersStatus : PNAcknowledgmentStatus // Members set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageChannelMembersData *data; @end ``` ### Manage channel members (builder pattern) #### Method(s) ```objectivec objects() .manageChannelMembers(NSString *) .set(NSArray *) .remove(NSArray *) .includeFields(PNChannelMemberFields) .includeCount(BOOL) .filter(NSString *) .sort(NSArray *) .limit(NSUInteger) .start(NSString *) .end(NSString *) .performWithCompletion(nullable PNManageChannelMembersCompletionBlock); ``` | Parameter | Description | | --- | --- | | `channel` *Type: NSString | Name of channel from which members should be managed. | | `set`Type: NSArray | List of `UUIDs` which should be added to `channel's` members list. Each entry is dictionary with `UUID` and `optional` `custom` fields. `custom` should be dictionary with simple objects: `NSString` and `NSNumber`. | | `remove`Type: NSArray | List of `UUIDs` which should be removed from `channel's` list. | | `includeFields`Type: PNChannelMemberFields | PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests., PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier)., PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests. | | `includeCount`Type: BOOL | Whether total count of objects should be included in response or not. Default: `YES` | | `filter`Type: NSString | Expression to filter out results basing on specified criteria. For more details on the supported grammar, check [App Context Filtering Language Definition](https://www.pubnub.com/docs/general/metadata/filtering). | | `sort`Type: NSArray | List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append `:asc` (*ascending* used by default) or `:desc` (descending) to field name. | | `limit`Type: NSUInteger | Maximum number of objects per fetched page. Default: `100` (which is also maximum value) | | `start`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. | | `end`Type: NSString | Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the `start` parameter is supplied. | | `block`Type: PNManageChannelMembersCompletionBlock | `Set channel's members` list request completion `block`. | :::note Optional arguments This method uses the builder pattern, you can remove the arguments which are optional. ::: #### Sample code ```objectivec NSArray *setMembers = @[ @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } } ]; NSArray *removeMembers = @[@"uuid3", @"uuid4"]; self.client.objects().manageChannelMembers(@"channel") .set(setMembers) .remove(removeMembers) .includeCount(YES) .limit(40) .includeFields(PNChannelMemberCustomField | PNChannelMemberUUIDField) .performWithCompletion(^(PNManageChannelMembersStatus *status) { if (!status.isError) { /** * Channel's members successfully changed. * Result object has following information: * result.data.members - List of existing channel's members. * result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. * result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. * result.data.totalCount - Total number of channel's members. */ } else { /** * Handle channel's members manage error. Check 'category' property to find out possible * issue because of which request did fail. * * Request can be resent using: [status retry] */ } }); ``` #### Response Response objects which is returned by client when `manage members` Object API is used: ```objectivec @interface PNManageChannelMembersData : PNServiceData // List of existing members. @property (nonatomic, readonly, strong) NSArray *members; // Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off. @property (nonatomic, nullable, readonly, strong) NSString *next; // Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. @property (nonatomic, nullable, readonly, strong) NSString *prev; /** * Total number of existing objects. * * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields' * of PNSetChannelMembersRequest / PNRemoveChannelMembersRequest / * PNManageChannelMembersRequest or PNFetchChannelMembersRequest. */ @property (nonatomic, readonly, assign) NSUInteger totalCount; @end @interface PNManageChannelMembersStatus : PNAcknowledgmentStatus // Members set / remove / manage request processed information. @property (nonatomic, readonly, strong) PNManageChannelMembersData *data; @end ```