Manage friends

Prerequisites

The managed hosting service is enabled by default.

Friend event listeners

Register a UserHandler before calling NCEngine.connect to receive friend events:

Callback	Trigger
onFriendAdd	Friendship established
onFriendRemove	Friendship removed
onFriendCleared	Server cleared the friend list
onFriendInfoChangedSync	Friend remark or extension updated on another device
onFriendApplicationStatusChanged	Friend request status changed

Dart

NCEngine.addUserHandler('friend-handler', UserHandler(
  onFriendAdd: (event) {
    print('Friend added: ${event.userId}');
  },
  onFriendRemove: (event) {
    print('Friends removed: ${event.userIds}');
  },
  onFriendInfoChangedSync: (event) {
    print('Friend info changed: ${event.userId}');
  },
  onFriendApplicationStatusChanged: (event) {
    print('Friend request status: ${event.applicationStatus} for ${event.userId}');
  },
));

Add a friend

Dart

await NCEngine.user.addFriend(
  AddFriendParams(userId: 'user1', extra: 'Hello'),
  (processCode, error) {
    if (error == null) print('Friend request sent');
  },
);

Set friend request permission

Enum	Description
notSet	No policy is configured yet. This value is returned by query APIs only and must not be passed to setFriendAddPermission.
free	Accept all requests
needVerify	Require approval
noOneAllowed	Reject all requests

Dart

await NCEngine.user.setFriendAddPermission(FriendAddPermission.needVerify, (error) {
  if (error?.isSuccess == true) print('Permission updated');
});

Get the current friend request permission

Use NCEngine.user.getFriendAddPermission() to query the current policy configured for the logged-in user.

Dart

await NCEngine.user.getFriendAddPermission((permission, error) {
  if (error == null) {
    print('Current permission: $permission');
  }
});

Remove friends

Dart

await NCEngine.user.removeFriends(
  ['user1', 'user2'],
  (error) {
    if (error?.isSuccess == true) print('Friends removed');
  },
);

Check friendship

Dart

await NCEngine.user.checkFriends(
  ['user1', 'user2'],
  (relationList, error) {
    if (error == null) print('Friend relations: $relationList');
  },
);

Handle friend requests

Get friend request list (paginated)

Dart

final query = NCEngine.user.createFriendApplicationsQuery(
  FriendApplicationsQueryParams(
    applicationTypes: [FriendApplicationType.received],
    applicationStatuses: [FriendApplicationStatus.unhandled],
    pageSize: 20,
  ),
);
await query.loadNextPage((result, error) {
  if (error == null) {
    print('Applications: ${result?.data}');
    print('Total matched: ${result?.totalCount}');
  }
});

Accept a friend request

Dart

await NCEngine.user.acceptFriendApplication('user1', (error) {
  if (error?.isSuccess == true) print('Request accepted');
});

Decline a friend request

Dart

await NCEngine.user.refuseFriendApplication('user1', (error) {
  if (error?.isSuccess == true) print('Request declined');
});

Get friend list

Dart

await NCEngine.user.getFriends((friends, error) {
  if (error == null) print('Friends: $friends');
});

Set friend info

Dart

final params = SetFriendInfoParams(userId: 'user1', remark: 'Nickname');
await NCEngine.user.setFriendInfo(params, (error) {
  if (error?.isSuccess == true) print('Friend info updated');
});

Get friend info by IDs

Dart

await NCEngine.user.getFriendsInfo(['user1', 'user2'], (friends, error) {
  if (error == null) print('Friend info: $friends');
});

Search friends by name

Dart

await NCEngine.user.searchFriendsInfo('Tom', (friends, error) {
  if (error == null) print('Search results: $friends');
});