Skip to main content

Group Query

This document guides developers on how to use RC IM IMLib SDK to implement functionalities such as retrieving joined groups and obtaining specific group information.

tip

This feature is supported starting from version 5.12.0.

Service Activation​

The information hosting service is enabled by default, allowing you to use this feature directly.

Group Query​

Retrieve Group Information​

You can call the getGroupsInfo method to obtain group information.

  • This method prioritizes local lookup. When the user is not in the group, or if the local group information cache exceeds 10 minutes, it will fetch the latest group information from the server.
  • A single call supports retrieving information for up to 20 groups, with a maximum of 5 queries per second.

Interface Prototype​

- (void)getGroupsInfo:(NSArray<NSString *> *)groupIds
              success:(void (^)(NSArray<RCGroupInfo *> *groupInfos))successBlock
                error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
groupIdsNSArrayList of targetIds for the groups to query. A single call supports retrieving information for up to 20 groups.
successBlockBlockSuccess callback, returning an array of corresponding group information RCGroupInfo.
errorBlockBlockFailure callback

Example Code​

[[RCCoreClient sharedCoreClient] getGroupsInfo:@[@"groupId1", @"groupId2"] 
    success:^(NSArray<RCGroupInfo *> * _Nonnull groupInfos) {
        // Retrieval successful
    } 
    error:^(RCErrorCode errorCode) {
        // Retrieval failed
    }
];

Retrieve Information for Specified Joined Groups​

You can use getJoinedGroups to obtain group information based on the group IDs of the groups the current user has joined.
This interface supports batch retrieval. You can pass multiple groupId values to fetch information for multiple groups, with a maximum of 20 groups per call.

Interface Prototype​

- (void)getJoinedGroups:(NSArray<NSString *> *)groupIds
                success:(void (^)(NSArray<RCGroupInfo *> *groupInfos))successBlock
                  error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
groupIdsNSArrayList of targetIds for the groups to query. A single call supports retrieving information for up to 20 groups.
successBlockBlockSuccess callback, returning an array of corresponding group information RCGroupInfo.
errorBlockBlockFailure callback.

Example Code​

// IDs of joined groups
NSArray *groupIds = @[@"groupId1", @"groupId2"];

// Retrieve joined groups
[[RCCoreClient sharedCoreClient] getJoinedGroups:groupIds success:^(NSArray<RCGroupInfo *> * _Nonnull groupInfos) {
    // Retrieval successful
} error:^(RCErrorCode errorCode) {
    // Retrieval failed
}];

Retrieve Joined Group Information by Role​

You can use getJoinedGroupsByRole to paginate and retrieve joined groups based on member roles.
The result in the success callback of this interface returns the total number of groups that meet the query criteria.

Interface Prototype​

- (void)getJoinedGroupsByRole:(RCGroupMemberRole)role
                       option:(RCPagingQueryOption *)option
                      success:(void (^)(RCPagingQueryResult<RCGroupInfo *> *result))successBlock
                        error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
roleRCGroupMemberRoleGroup member role.
optionRCPagingQueryOptionQuery options, including page token (optional, omit to return the first page of data), number of items per page (maximum 100), and whether to sort in ascending order (default is descending).
successBlockBlockSuccess callback, returning an array of related query data RCPagingQueryResult.
errorBlockBlockFailure callback.

Type: RCGroupMemberRole

Enum ValueGroup Member Role
RCGroupMemberRoleUndefUndefined role (using this enum queries all types of group members)
RCGroupMemberRoleNormalRegular group member
RCGroupMemberRoleManagerAdministrator
RCGroupMemberRoleOwnerGroup owner

Type: RCPagingQueryOption

ParameterTypeDescription
pageTokenNSStringPage token. For the first fetch, pass nil or @"". If the result (type RCPagingQueryResult) returned in the success callback has a pageToken that is not @"", you can pass this value to fetch the next page until pageToken returns @"", indicating all data has been fetched.
countNSIntegerNumber of items per page, with a maximum of 200 per page.
orderBOOLSort by group join time (default is NO for descending, YES for ascending).

Example Code​

- (void)getJoinedGroupsByRole:(NSString *)pageToken {
    // Specify the role to retrieve, example shows all roles
    RCGroupMemberRole role = RCGroupMemberRoleUndef;
    
    // Query options
    RCPagingQueryOption *option = [[RCPagingQueryOption alloc] init];
    // Page token, pass nil for the first page
    option.pageToken = pageToken;
    // Number of items per page
    option.count = 20;
    // Default NO for descending by join time, YES for ascending
    option.order = NO;
    
    // Retrieve groups for the specified role
    [[RCCoreClient sharedCoreClient] getJoinedGroupsByRole:role option:option 
        success:^(RCPagingQueryResult<RCGroupInfo *> * _Nonnull result) {
            // Query successful
            if (result.pageToken.length > 0) {
                // Continue fetching the next page
                [self getJoinedGroupsByRole:result.pageToken];
            } else {
                // Fetch complete, no more data
            }
    } error:^(RCErrorCode errorCode) {
        // Retrieval failed
    }];
}

Search Joined Groups by Group Name​

You can use searchJoinedGroups to search joined groups by group name.
The result in the success callback of this interface returns the total number of groups that meet the query criteria.

Interface Prototype​

- (void)searchJoinedGroups:(NSString *)groupName
                    option:(RCPagingQueryOption *)option
                   success:(void (^)(RCPagingQueryResult<RCGroupInfo *> *result))successBlock
                     error:(void (^)(RCErrorCode errorCode))errorBlock;

Parameter Description​

ParameterTypeDescription
groupNameNSStringGroup name, cannot be empty and must not exceed 64 characters.
optionRCPagingQueryOptionQuery options, including page token (optional, omit to return the first page of data), number of items per page (maximum 100), and whether to sort in ascending order (default is descending).
successBlockBlockSuccess callback, returning an array of related query data RCPagingQueryResult.
errorBlockBlockFailure callback.

Type: RCPagingQueryOption

ParameterTypeDescription
pageTokenNSStringPage token. For initial fetch, pass nil or @"". If the returned result (type RCPagingQueryResult) contains a non-empty pageToken, pass this value for subsequent fetches until pageToken returns as @"", indicating all data has been fetched.
countNSIntegerNumber of items per page (maximum 200)
orderBOOLSort by group join time (default NO for descending, YES for ascending)

Sample Code​



- (void)searchJoinedGroups:(NSString *)pageToken {
    // Group name to search
    NSString *groupName = @"groupName";

    // Query options
    RCPagingQueryOption *option = [[RCPagingQueryOption alloc] init];
    // Page token, pass nil for first page
    option.pageToken = pageToken;
    // Items per page
    option.count = 20;
    // Default NO for descending by join time, YES for ascending
    option.order = NO;

    [[RCCoreClient sharedCoreClient] searchJoinedGroups:groupName option:option
        success:^(RCPagingQueryResult<RCGroupInfo *> * _Nonnull result) {
            // Search succeeded
            if (result.pageToken.length > 0) {
                // Continue fetching next page
                [self searchJoinedGroups:result.pageToken];
            } else {
                // Search completed, no more data
            }
    } error:^(RCErrorCode errorCode) {
       // Search failed
    }];
}
Last updated on