KiiGroup Class Reference

Inherits from	NSObject
Conforms to	KiiThingOwner
Declared in	KiiGroup.h

Overview

A reference to a group of users within the application

Tasks

name property
groupID property
objectURI property
+ groupWithName:
+ groupWithName:andMembers:
+ groupWithURI:
+ groupWithID:
– bucketWithName:
– encryptedBucketWithName:
– topicWithName:
– addUser:
– removeUser:
– getMemberListWithBlock:
– getMemberListSynchronous:
– getMemberList:withCallback:
– getOwnerWithBlock:
– getOwnerSynchronous:
– getOwner:withCallback:
– getCachedOwner
– refreshWithBlock:
– refreshSynchronous:
– refresh:withCallback:
– saveWithBlock:
– saveSynchronous:
– save:withCallback:
– deleteWithBlock:
– deleteSynchronous:
– delete:withCallback:
– changeGroupName:withBlock:
– changeGroupNameSynchronous:withError:
– changeGroupName:withDelegate:andCallback:
– describe
– listTopicsSynchronous:
– listTopicsSynchronous:error:
– listTopics:
– listTopics:block:
+ registerGroupSynchronousWithID:name:members:error:
+ registerGroupWithID:name:members:block:

Properties

groupID

The ID of the KiiGroup, assigned by the server.

@property (readonly, nullable) NSString *groupID

Discussion

The ID of the KiiGroup, assigned by the server.

Declared In

KiiGroup.h

name

The name of the group

@property (readonly, nullable) NSString *name

Discussion

The name of the group

Declared In

KiiGroup.h

objectURI

Get a specifically formatted string referencing the group. The group must exist in the cloud (have a valid UUID).

@property (strong, readonly, nullable) NSString *objectURI

Discussion

Get a specifically formatted string referencing the group. The group must exist in the cloud (have a valid UUID).

Declared In

KiiGroup.h

Class Methods

groupWithID:

Instantiate KiiGroup that refers to existing group which has specified ID.

+ (KiiGroup *)groupWithID:(NSString *)groupID

Parameters

groupID: ID of the KiiGroup to instantiate.

Return Value

instance of KiiGroup.

Discussion

Instantiate KiiGroup that refers to existing group which has specified ID.

You have to specify the ID of existing KiiGroup. Unlike KiiObject, you can not assign ID in the client side.

Note: This API does not access to the server.After instantiation, it should be ‘refreshed’ to fetch the properties from server.

Declared In

KiiGroup.h

groupWithName:

Creates a reference to a group with the given name

+ (KiiGroup *)groupWithName:(NSString *)groupName

Parameters

groupName: An application-specific group name

Return Value

a working

Discussion

Creates a reference to a group with the given name

If the group already exists, it should be be ‘refreshed’ to fill the data from the server

Declared In

KiiGroup.h

groupWithName:andMembers:

Creates a reference to a group with the given name with default members

+ (KiiGroup *)groupWithName:(NSString *)groupName andMembers:(nullable NSArray *)members

Parameters

groupName: An application-specific group name

members: An array of members to automatically add to the group upon creation

Return Value

a working

Discussion

Creates a reference to a group with the given name with default members

If the group already exists, it should be be ‘refreshed’ to fill the data from the server

Declared In

KiiGroup.h

groupWithURI:

Creates a reference to a group with the given URI

+ (KiiGroup *)groupWithURI:(NSString *)groupURI

Parameters

groupURI: An application-specific group URI

Return Value

a working

Discussion

Creates a reference to a group with the given URI

To utilize existing group data, the group should be be ‘refreshed’ to fill the data from the server

Declared In

KiiGroup.h

registerGroupSynchronousWithID:name:members:error:

+ (nullable KiiGroup *)registerGroupSynchronousWithID:(NSString *)groupID name:(NSString *)name members:(nullable NSArray *)members error:(NSError *_Nullable *_Nullable)error

Parameters

groupID: id of the KiiGroup. This groupID is mandatory. must not be nil or empty.

name: Name of the KiiGroup. name is mandatory. must not be nil or empty.

members: Members of the group. Group owner will be added as a group member no matter owner is in the list or not. members are optional. This can be nil. Contents of members must be <[KiiUser]> object.

error

On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You can specify nil if you want to skip checking error. But we recommend you to check error and handle it properly. to check error.

If response can not be parsed, error code 202 is returned.
If access token is invalid, error code 203 is returned.
If user is not logged in, error code 327 is returned.
If name is invalid, error code 513 is returned.
If groupID is invalid, error code 524 is returned.
If contents of members is not KiiUser instance, error code 525 is returned.
If group id is already exists, error code 526 is returned.

Return Value

KiiGroup instance.

Discussion

NOTE: This api access to server. Should not be executed in UI/Main thread.

Declared In

KiiGroup.h

registerGroupWithID:name:members:block:

Asynchronous call for [KiiGroup registerGroupSynchronousWithID:name:members:error:], A background task will be initiated to execute the task.

+ (void)registerGroupWithID:(NSString *)groupID name:(NSString *)name members:(nullable NSArray *)members block:(KiiGroupBlock)block

Parameters

groupID: id of the KiiGroup. This groupID is mandatory. must not be nil or empty.

name: Name of the KiiGroup. name is mandatory. must not be nil or empty.

members: Members of the group. Group owner will be added as a group member no matter owner is in the list or not. members are optional. This can be nil. Contents of members must be <[KiiUser]> object.

block: The block to be called upon method completion. block is mandatory. must not be nil. See example.

Discussion

Asynchronous call for [KiiGroup registerGroupSynchronousWithID:name:members:error:], A background task will be initiated to execute the task.

 [KiiGroup registerGroupWithID:@"your group id"
                          name:@"your group name"
                       members:groupArray
                         block:^(KiiGroup *group, NSError *error) {
         if(error == nil) {
             NSLog(@"Group saved: %@", group);
         }
 }];

Exceptions

NSInvalidArgumentException: if block is nil.

Declared In

KiiGroup.h

Instance Methods

addUser:

Adds a user to the given group

- (void)addUser:(nullable KiiUser *)user

Parameters

user: The user that should be added to the group. No effect if nil passed.

Discussion

Adds a user to the given group

This method will NOT access the server immediately. You must call save to add the user on the server. This allows multiple users to be added before calling save.

Declared In

KiiGroup.h

bucketWithName:

Creates a reference to a bucket that is within the group’s scope

- (KiiBucket *)bucketWithName:(NSString *)bucketName

Parameters

bucketName: The name of the bucket you’d like to use

Return Value

An instance of a working KiiBucket

Discussion

Creates a reference to a bucket that is within the group’s scope

If the bucket exists, it should be ‘refreshed’ to pull the latest information from the server. Otherwise, the bucket must be written to or explicitly created on the server before it will persist.

Declared In

KiiGroup.h

changeGroupName:withBlock:

Asynchronously updates the group name on the server

- (void)changeGroupName:(NSString *)groupName withBlock:(KiiGroupBlock)block

Parameters

groupName: An NSString of the desired group name

block: The block to be called upon method completion. See example

Discussion

Asynchronously updates the group name on the server

This method is non-blocking.

 [g changeGroupName:@"new_group_name" withBlock:^(KiiGroup *group, NSError *error) {
     if(error == nil) {
         NSLog(@"Group name changed!");
     }
 }];

Declared In

KiiGroup.h

changeGroupName:withDelegate:andCallback:

Asynchronously updates the group name on the server

- (void)changeGroupName:(NSString *)groupName withDelegate:(id)delegate andCallback:(SEL)callback

Parameters

groupName: An NSString of the desired group name

delegate: The object to make any callback requests to

callback

The callback method to be called when the request is completed. The callback method should have a signature similar to:

 - (void) groupNameUpdated:(KiiGroup*)group withError:(NSError*)error {

     // the request was successful
     if(error == nil) {
         // do something
     }

     else {
         // there was a problem
     }
 }

Discussion

Asynchronously updates the group name on the server

This method is non-blocking.

Declared In

KiiGroup.h

changeGroupNameSynchronous:withError:

Synchronously updates the group name on the server

- (BOOL)changeGroupNameSynchronous:(NSString *)groupName withError:(NSError *_Nullable *_Nullable)error

Parameters

groupName: An NSString of the desired group name

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

YES if succeeded, NO otherwise.

Discussion

Synchronously updates the group name on the server

This method is blocking.

Declared In

KiiGroup.h

delete:withCallback:

Asynchronously deletes a group from the server.

- (void)delete:(id)delegate withCallback:(SEL)callback

Parameters

delegate: The object to make any callback requests to

callback

The callback method to be called when the request is completed. The callback method should have a signature similar to:

 - (void) groupDeleted:(KiiGroup*)group withError:(NSError*)error {

     // the request was successful
     if(error == nil) {
         // do something
     }

     else {
         // there was a problem
     }
 }

Discussion

Asynchronously deletes a group from the server.

Delete a group from the server. This method is non-blocking.

Declared In

KiiGroup.h

deleteSynchronous:

Synchronously deletes a group from the server.

- (BOOL)deleteSynchronous:(NSError *_Nullable *_Nullable)error

Parameters

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

YES if succeeded, NO otherwise.

Discussion

Synchronously deletes a group from the server.

Delete a group from the server. This method is blocking.

Declared In

KiiGroup.h

deleteWithBlock:

Asynchronously deletes a group from the server.

- (void)deleteWithBlock:(KiiGroupBlock)block

Parameters

block: The block to be called upon method completion. See example

Discussion

Asynchronously deletes a group from the server.

Delete a group from the server. This method is non-blocking.

 [g deleteWithBlock:^(KiiGroup *group, NSError *error) {
     if(error == nil) {
         NSLog(@"Group deleted!");
     }
 }];

Declared In

KiiGroup.h

describe

Prints the contents of this object to log

- (void)describe

Discussion

Prints the contents of this object to log

For developer purposes only, this method prints the object in a readable format to the log for testing.

Declared In

KiiGroup.h

encryptedBucketWithName:

Get or create an encrypted bucket at the group level.

- (KiiEncryptedBucket *)encryptedBucketWithName:(NSString *)bucketName

Parameters

bucketName: The name of the encrypted bucket you’d like to use.

Return Value

An instance of a working KiiEncryptedBucket

Discussion

Get or create an encrypted bucket at the group level.

Exceptions

NSInvalidArgumentException: when bucketName is not acceptable format. For details please refer to <[KiiBucket isValidBucketName:(NSString*) bucketName]>.

Declared In

KiiGroup.h

getCachedOwner

Returns the owner of this group if this group holds the information of owner.

- (nullable KiiUser *)getCachedOwner

Return Value

A KiiUser object who owns this group, nil if this group doesn’t hold the information of owner yet.

Discussion

Returns the owner of this group if this group holds the information of owner.

Group will holds the information of owner when “saving group on cloud” or “retrieving group info/owner from cloud”. The cache will not be shared among the different instances of KiiGroup.

Note: This API will not access to server. To update the group owner information on cloud, please call KiiGroup refresh or getOwner methods.

Warning: This API does not return all the properties of the owner. To get all owner properties, KiiUser refresh is necessary.

Declared In

KiiGroup.h

getMemberList:withCallback:

Asynchronously gets a list of all current members in a group

- (void)getMemberList:(id)delegate withCallback:(SEL)callback

Parameters

delegate: The object to make any callback requests to

callback

The callback method to be called when the request is completed. The callback method should have a signature similar to:

 - (void) gotMemberList:(nullable NSArray*)members inGroup:(KiiGroup*)group withError:(NSError*)error {

     if(error == nil) {
         // successfully got the list, do something with it
         for(KiiUser *user in members) {
             // do something with the user
         }
     }

     else {
         // there was a problem
     }
 }

Discussion

Asynchronously gets a list of all current members in a group

This method is non-blocking.

Declared In

KiiGroup.h

getMemberListSynchronous:

Gets a list of all current members of a group

- (nullable NSArray *)getMemberListSynchronous:(NSError *_Nullable *_Nullable)error

Parameters

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

An NSArray of KiiUser objects

Discussion

Gets a list of all current members of a group

Returns an array of KiiUser objects if successful. This method is blocking.

Declared In

KiiGroup.h

getMemberListWithBlock:

Asynchronously gets a list of all current members in a group

- (void)getMemberListWithBlock:(KiiGroupMemberBlock)block

Parameters

block: The block to be called upon method completion. See example

Discussion

Asynchronously gets a list of all current members in a group

This method is non-blocking.

 [g getMemberListWithBlock:^(KiiGroup *group, NSArray *members, NSError *error) {
     if(error == nil) {
         NSLog(@"Got members: %@", members);
     }
 }];

Declared In

KiiGroup.h

getOwner:withCallback:

Asynchronously gets the owner of the associated group

- (void)getOwner:(id)delegate withCallback:(SEL)callback

Parameters

delegate: The object to make any callback requests to

callback

The callback method to be called when the request is completed. The callback method should have a signature similar to:

 - (void) gotOwner:(KiiUser*)owner inGroup:(KiiGroup*)group withError:(NSError*)error {

     if(error == nil) {
         // successfully got the owner, do something with it
     }

     else {
         // there was a problem
     }
 }

Discussion

Asynchronously gets the owner of the associated group

Receives a KiiUser object representing the group’s owner. This is a non-blocking request.

Declared In

KiiGroup.h

getOwnerSynchronous:

Gets the owner of the associated group

- (nullable KiiUser *)getOwnerSynchronous:(NSError *_Nullable *_Nullable)error

Parameters

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

A KiiUser object representing the current group’s owner

Discussion

Gets the owner of the associated group

Returns a KiiUser object for this group’s owner. This is a blocking method.

Declared In

KiiGroup.h

getOwnerWithBlock:

Asynchronously gets the owner of the associated group

- (void)getOwnerWithBlock:(KiiGroupOwnerBlock)block

Parameters

block: The block to be called upon method completion. See example

Discussion

Asynchronously gets the owner of the associated group

Receives a KiiUser object representing the group’s owner. This is a non-blocking request.

 [g getOwnerWithBlock:^(KiiGroup *group, KiiUser *owner, NSError *error) {
     if(error == nil) {
         NSLog(@"Got owner: %@", owner);
     }
 }];

Declared In

KiiGroup.h

listTopics:

Returns the topics in this group scope asynchronously.

- (void)listTopics:(KiiListResultBlock)completion

Parameters

completion: The block to be called upon method completion, this is mandatory. See example.

Discussion

Returns the topics in this group scope asynchronously.

Receives a KiiListResult object representing list of topics. This is a non-blocking request.

[g listTopics:^(KiiListResult *topics, id callerObject, NSError *error){
   //at this scope, callerObject should be KiiGroup instance
   NSLog(@"%@",callerObject);
   if(error == nil) {
        NSLog(@"Got Results: %@", topics);
        NSLog(@"Total topics: %@", topics.results.count);
        NSLog(@"Has Next: %@ next paginationKey: %@", topics.hasNext?@"Yes":@"No", topics.paginationKey);
        KiiTopic *firstTopic = topics.result.firstObject;
        if (firstTopic){
            NSLog(@"topic name :%@", firstTopic.name);
        }
   }
}];

Exceptions

NSInvalidArgumentException: if completion is nil.

Declared In

KiiGroup.h

listTopics:block:

Returns the topics in this group scope asynchronously.

- (void)listTopics:(nullable NSString *)paginationKey block:(KiiListResultBlock)completion

Parameters

paginationKey: pagination key. If nil or empty value is specified, this API regards no paginationKey specified.

completion: The block to be called upon method completion, this is mandatory. See example.

Discussion

Returns the topics in this group scope asynchronously.

Receives a KiiListResult object representing list of topics. This is a non-blocking request.

[g listTopics:paginationKey block:^(KiiListResult *topics, id callerObject, NSError *error){
   //at this scope, callerObject should be KiiGroup instance
   NSLog(@"%@",callerObject);
   if(error == nil) {
        NSLog(@"Got Results: %@", topics);
        NSLog(@"Total topics: %@", topics.results.count);
        NSLog(@"Has Next: %@ next paginationKey: %@", topics.hasNext?@"Yes":@"No", topics.paginationKey);
        KiiTopic *firstTopic = topics.result.firstObject;
        if (firstTopic){
            NSLog(@"topic name :%@", firstTopic.name);
        }
   }
}];

Exceptions

NSInvalidArgumentException: if completion is nil.

Declared In

KiiGroup.h

listTopicsSynchronous:

Returns the topics in this group scope. This is blocking method.

- (nullable KiiListResult *)listTopicsSynchronous:(NSError *_Nullable *_Nullable)error

Parameters

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

a KiiListResult object representing list of topics in this group scope.

Discussion

Returns the topics in this group scope. This is blocking method.

Declared In

KiiGroup.h

listTopicsSynchronous:error:

Returns the topics in this group scope. This is blocking method.

- (nullable KiiListResult *)listTopicsSynchronous:(nullable NSString *)paginationKey error:(NSError *_Nullable *_Nullable)error

Parameters

paginationKey: pagination key. If nil or empty value is specified, this API regards no paginationKey specified.

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

a KiiListResult object representing list of topics in this group scope.

Discussion

Returns the topics in this group scope. This is blocking method.

Declared In

KiiGroup.h

refresh:withCallback:

Asynchronously updates the local group’s data with the group data on the server

- (void)refresh:(id)delegate withCallback:(SEL)callback

Parameters

delegate: The object to make any callback requests to

callback

The callback method to be called when the request is completed. The callback method should have a signature similar to:

 - (void) groupRefreshed:(KiiGroup*)object withError:(NSError*)error {

    // the request was successful
    if(error == nil) {
        // do something with the object
    }

    else {
        // there was a problem
    }
 }

Discussion

Asynchronously updates the local group’s data with the group data on the server

The group must exist on the server. Local data will be overwritten.

Declared In

KiiGroup.h

refreshSynchronous:

Synchronously updates the local object’s data with the object data on the server

- (BOOL)refreshSynchronous:(NSError *_Nullable *_Nullable)error

Parameters

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

YES if succeeded, NO otherwise.

Discussion

Synchronously updates the local object’s data with the object data on the server

The group must exist on the server. Local data will be overwritten. This is a blocking method.

Declared In

KiiGroup.h

refreshWithBlock:

Asynchronously updates the local group’s data with the group data on the server

- (void)refreshWithBlock:(KiiGroupBlock)block

Parameters

block: The block to be called upon method completion. See example

Discussion

Asynchronously updates the local group’s data with the group data on the server

The group must exist on the server. Local data will be overwritten.

 [g refreshWithBlock:^(KiiGroup *group, NSError *error) {
     if(error == nil) {
         NSLog(@"Group refreshed: %@", group);
     }
 }];

Declared In

KiiGroup.h

removeUser:

Removes a user to the given group

- (void)removeUser:(nullable KiiUser *)user

Parameters

user: The user that should be removed from the group. No effect if nil passed.

Discussion

Removes a user to the given group

This method will NOT access the server immediately. You must call save to remove the user from the server. This allows multiple users to be removed before calling save.

Declared In

KiiGroup.h

save:withCallback:

Asynchronously saves the latest group information to the server

- (void)save:(id)delegate withCallback:(SEL)callback

Parameters

delegate: The object to make any callback requests to

callback

The callback method to be called when the request is completed. The callback method should have a signature similar to:

 - (void) groupSaved:(KiiGroup*)group withError:(NSError*)error {

    // the request was successful
    if(error == nil) {
        // do something with the group
    }

    else {
        // there was a problem
    }
 }

Discussion

Asynchronously saves the latest group information to the server

If the group does not yet exist, it will be created. If the group already exists, the information that has changed will be updated accordingly. This is a non-blocking method.

Declared In

KiiGroup.h

saveSynchronous:

Synchronously saves the latest group information to the server

- (BOOL)saveSynchronous:(NSError *_Nullable *_Nullable)error

Parameters

error: used to return an error by reference (pass NULL if this is not desired). It is recommended to set an actual error object to get the error information.

Return Value

YES if succeeded, NO otherwise.

Discussion

Synchronously saves the latest group information to the server

If the group does not yet exist, it will be created. If the group already exists, the information that has changed will be updated accordingly. This is a blocking method.

Declared In

KiiGroup.h

saveWithBlock:

Asynchronously saves the latest group information to the server

- (void)saveWithBlock:(KiiGroupBlock)block

Parameters

block: The block to be called upon method completion. See example

Discussion

Asynchronously saves the latest group information to the server

If the group does not yet exist, it will be created. If the group already exists, the information that has changed will be updated accordingly. This is a non-blocking method.

 [g saveWithBlock:^(KiiGroup *group, NSError *error) {
     if(error == nil) {
         NSLog(@"Group saved: %@", group);
     }
 }];

Declared In

KiiGroup.h

topicWithName:

Get or create a Push notification topic at the group level

- (KiiTopic *)topicWithName:(NSString *)topicName

Parameters

topicName: The name of the topic you’d like to use. It has to match the pattern ^[A-Za-z0-9-]{1,64}$, that is letters, numbers, ‘-’ and ‘’ and non-multibyte characters with a length between 1 and 64 characters.

Return Value

An instance of a working KiiTopic

Discussion

Get or create a Push notification topic at the group level

Declared In

KiiGroup.h