Skip to content

Commit

Permalink
1. Add detailed docs on each service API for all clients
Browse files Browse the repository at this point in the history 
2. Support recalling friend request on all clients
3. Support replying group invitation and join request on all clients
4. Sync the latest status codes on all clients
  • Loading branch information
@JamesChenX
JamesChenX committed Feb 9, 2024
1 parent 0c3f1c0 commit 5c0dce4
Show file tree
Hide file tree
Showing 35 changed files with 7,797 additions and 256 deletions.
119 changes: 69 additions & 50 deletions turms-client-cpp/include/turms/client/model/response_status_code.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,21 +100,25 @@ const int kQueryingNearestUsersBySessionIdIsDisabled = 2201;

// User - Info
const int kUpdateInfoOfNonexistentUser = 2300;
const int kUserProfileNotFound = 2301;
const int kProfileRequesterNotInContactsOrBlocked = 2302;
const int kProfileRequesterHasBeenBlocked = 2303;
const int kNotFriendToQueryUserProfile = 2301;
const int kBlockedUserToQueryUserProfile = 2302;

// User - Permission
const int kQueryPermissionOfNonexistentUser = 2400;

// User - Relationship
const int kAddNonRelatedUserToGroup = 2500;
const int kCreateExistingRelationship = 2501;
const int kCannotBlockOneself = 2502;

// User - Friend Request
const int kRequesterNotFriendRequestRecipient = 2600;
const int kCreateExistingFriendRequest = 2601;
const int kFriendRequestSenderHasBeenBlocked = 2602;
const int kCreateExistingFriendRequest = 2600;
const int kBlockedUserToSendFriendRequest = 2601;
const int kRecallNonPendingFriendRequest = 2602;
const int kRecallingFriendRequestIsDisabled = 2603;
const int kNotSenderToRecallFriendRequest = 2604;
const int kUpdateNonPendingFriendRequest = 2605;
const int kNotRecipientToUpdateFriendRequest = 2606;

// Group

Expand All @@ -127,21 +131,25 @@ const int kNotGroupMemberToUpdateGroupInfo = 3003;
// Group - Type
const int kNoPermissionToCreateGroupWithGroupType = 3100;
const int kCreateGroupWithNonexistentGroupType = 3101;
const int kUpdatingGroupTypeIsDisabled = 3102;
const int kNotGroupOwnerToUpdateGroupType = 3103;
const int kNoPermissionToUpdateGroupToGroupType = 3104;
const int kUpdateGroupToNonexistentGroupType = 3105;

// Group - Ownership
const int kNotActiveUserToCreateGroup = 3200;
const int kNotGroupOwnerToTransferGroup = 3201;
const int kNotGroupOwnerToDeleteGroup = 3202;
const int kSuccessorNotGroupMember = 3203;
const int kOwnerQuitsWithoutSpecifyingSuccessor = 3204;
const int kGroupSuccessorNotGroupMember = 3203;
const int kGroupOwnerQuitWithoutSpecifyingSuccessor = 3204;
const int kMaxOwnedGroupsReached = 3205;
const int kTransferNonexistentGroup = 3206;

// Group - Question
const int kNotGroupOwnerOrManagerToCreateGroupQuestion = 3300;
const int kNotGroupOwnerOrManagerToDeleteGroupQuestion = 3301;
const int kNotGroupOwnerOrManagerToUpdateGroupQuestion = 3302;
const int kNotGroupOwnerOrManagerToAccessGroupQuestionAnswer = 3303;
const int kNotGroupOwnerOrManagerToQueryGroupQuestionAnswer = 3303;
const int kCreateGroupQuestionForInactiveGroup = 3304;
const int kCreateGroupQuestionForGroupUsingJoinRequest = 3305;
const int kCreateGroupQuestionForGroupUsingInvitation = 3306;
Expand All @@ -152,54 +160,64 @@ const int kAnswerInactiveGroupQuestion = 3310;
const int kAnswerGroupQuestionOfInactiveGroup = 3311;

// Group - Member
const int kAddUserToGroupRequiringInvitation = 3400;
const int kAddUserToGroupRequiringUsersApproval = 3400;
const int kAddUserToInactiveGroup = 3401;
const int kAddUserToGroupWithRoleHigherThanRequester = 3402;
const int kNotGroupOwnerToAddGroupManager = 3402;
const int kAddUserToGroupWithSizeLimitReached = 3403;
const int kAddBlockedUserToGroup = 3404;
const int kAddBlockedUserToInactiveGroup = 3405;
const int kNotGroupOwnerOrManagerToRemoveGroupMember = 3406;
const int kNotGroupOwnerToRemoveGroupOwnerOrManager = 3407;
const int kNotGroupOwnerToUpdateGroupMemberRole = 3408;
const int kUpdateGroupMemberRoleOfNonexistentGroup = 3409;
const int kNotGroupOwnerToUpdateGroupMemberInfo = 3410;
const int kNotGroupOwnerOrManagerToUpdateGroupMemberInfo = 3411;
const int kNotGroupMemberToUpdateGroupMemberInfo = 3412;
const int kUpdateGroupMemberInfoOfNonexistentGroup = 3413;
const int kUpdateInfoOfNonexistentGroupMember = 3414;
const int kNotGroupOwnerOrManagerToMuteGroupMember = 3415;
const int kMuteGroupMemberWithRoleEqualToOrHigherThanRequester = 3416;
const int kMuteGroupMemberOfNonexistentGroup = 3417;
const int kMuteNonexistentGroupMember = 3418;
const int kNotGroupMemberToQueryGroupMemberInfo = 3419;
const int kNotGroupOwnerToAddGroupMember = 3405;
const int kNotGroupOwnerOrManagerToAddGroupMember = 3406;
const int kNotGroupMemberToAddGroupMember = 3407;
const int kNotGroupOwnerOrManagerToRemoveGroupMember = 3408;
const int kNotGroupOwnerToRemoveGroupOwnerOrManager = 3409;
const int kNotGroupOwnerToUpdateGroupMemberRole = 3410;
const int kUpdateGroupMemberRoleOfNonexistentGroup = 3411;
const int kNotGroupOwnerToUpdateGroupMemberInfo = 3412;
const int kNotGroupOwnerOrManagerToUpdateGroupMemberInfo = 3413;
const int kNotGroupMemberToUpdateGroupMemberInfo = 3414;
const int kUpdateGroupMemberInfoOfNonexistentGroup = 3415;
const int kUpdateInfoOfNonexistentGroupMember = 3416;
const int kNotGroupOwnerOrManagerToMuteGroupMember = 3417;
const int kMuteGroupMemberWithRoleEqualToOrHigherThanRequester = 3418;
const int kMuteGroupMemberOfNonexistentGroup = 3419;
const int kMuteNonexistentGroupMember = 3420;
const int kNotGroupMemberToQueryGroupMemberInfo = 3421;
const int kUserJoinGroupWithoutAcceptingGroupInvitation = 3422;
const int kUserJoinGroupWithoutAnsweringGroupQuestion = 3423;
const int kUserJoinGroupWithoutSendingGroupJoinRequest = 3424;

// Group - Blocklist
const int kNotGroupOwnerOrManagerToAddBlockedUser = 3500;
const int kNotGroupOwnerOrManagerToRemoveBlockedUser = 3501;

// Group - Join Request
const int kGroupJoinRequestSenderHasBeenBlocked = 3600;
const int kNotGroupJoinRequestSenderToRecallRequest = 3601;
const int kNotGroupOwnerOrManagerToAccessGroupJoinRequest = 3602;
const int kRecallNonPendingGroupJoinRequest = 3603;
const int kSendGroupJoinRequestToInactiveGroup = 3604;
const int kSendGroupJoinRequestToGroupUsingMembershipRequest = 3605;
const int kSendGroupJoinRequestToGroupUsingInvitation = 3606;
const int kSendGroupJoinRequestToGroupUsingQuestion = 3607;
const int kRecallingGroupJoinRequestIsDisabled = 3608;
const int kBlockedUserSendGroupJoinRequest = 3600;
const int kGroupMemberSendGroupJoinRequest = 3601;
const int kNotSenderToRecallGroupJoinRequest = 3602;
const int kNotGroupOwnerOrManagerToQueryGroupJoinRequest = 3603;
const int kRecallNonPendingGroupJoinRequest = 3604;
const int kSendGroupJoinRequestToInactiveGroup = 3605;
const int kSendGroupJoinRequestToGroupUsingMembershipRequest = 3606;
const int kSendGroupJoinRequestToGroupUsingInvitation = 3607;
const int kSendGroupJoinRequestToGroupUsingQuestion = 3608;
const int kRecallingGroupJoinRequestIsDisabled = 3609;
const int kUpdateNonPendingGroupJoinRequest = 3610;
const int kNotGroupOwnerOrManagerToUpdateGroupJoinRequest = 3611;

// Group - Invitation
const int kGroupInviterNotGroupMember = 3700;
const int kGroupInviteeAlreadyGroupMember = 3701;
const int kGroupInviteeHasBeenBlockedByGroup = 3702;
const int kNotGroupOwnerOrManagerToRecallGroupInvitation = 3703;
const int kNotGroupOwnerOrManagerToAccessGroupInvitation = 3704;
const int kNotGroupOwnerToSendGroupInvitation = 3705;
const int kNotGroupOwnerOrManagerToSendGroupInvitation = 3706;
const int kNotGroupMemberToSendGroupInvitation = 3707;
const int kRecallingGroupInvitationIsDisabled = 3708;
const int kSendGroupInvitationToGroupNotRequireInvitation = 3709;
const int kRecallNonPendingGroupInvitation = 3710;
const int kSendGroupInvitationToGroupMember = 3700;
const int kSendGroupInvitationToBlockedUser = 3701;
const int kSendGroupInvitationToGroupNotRequiringUsersApproval = 3702;
const int kNotGroupOwnerToSendGroupInvitation = 3703;
const int kNotGroupOwnerOrManagerToSendGroupInvitation = 3704;
const int kNotGroupMemberToSendGroupInvitation = 3705;
const int kRecallingGroupInvitationIsDisabled = 3706;
const int kNotGroupOwnerOrManagerToRecallGroupInvitation = 3707;
const int kNotGroupOwnerOrManagerOrSenderToRecallGroupInvitation = 3708;
const int kRecallNonPendingGroupInvitation = 3709;
const int kUpdateNonPendingGroupInvitation = 3710;
const int kNotInviteeToUpdateGroupInvitation = 3711;
const int kNotGroupOwnerOrManagerToQueryGroupInvitation = 3712;

// Conversation

Expand All @@ -219,16 +237,17 @@ const int kNotFriendToSendTypingStatus = 4102;

// Message - Send
const int kMessageRecipientNotActive = 5000;
const int kMessageSenderNotInContactsOrBlocked = 5001;
const int kPrivateMessageSenderHasBeenBlocked = 5002;
const int kGroupMessageSenderHasBeenBlocked = 5003;
const int kNotFriendToSendPrivateMessage = 5001;
const int kBlockedUserSendPrivateMessage = 5002;
const int kBlockedUserSendGroupMessage = 5003;
const int kSendMessageToInactiveGroup = 5004;
const int kSendMessageToMutedGroup = 5005;
const int kSendMessageToNonexistentGroup = 5006;
const int kSendingMessagesToOneselfIsDisabled = 5007;
const int kMutedGroupMemberSendMessage = 5008;
const int kGuestsHaveBeenMuted = 5009;
const int kNotSpeakableGroupGuestToSendMessage = 5009;
const int kMessageIsIllegal = 5010;
const int kNotMessageRecipientOrSenderToForwardMessage = 5011;

// Message - Update
const int kUpdatingMessageBySenderIsDisabled = 5100;
Expand Down
126 changes: 126 additions & 0 deletions turms-client-cpp/include/turms/client/service/conversation_service.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ namespace service {
class ConversationService : private boost::noncopyable {
private:
using time_point = std::chrono::time_point<std::chrono::system_clock>;
using ResponseException = exception::ResponseException;

template <typename T>
using Response = model::Response<T>;
Expand All @@ -33,22 +34,147 @@ class ConversationService : private boost::noncopyable {
public:
explicit ConversationService(TurmsClient& turmsClient);

/**
* Find private conversations between the logged-in user and another user.
*
* Common Scenarios:
* * If you want to find all private conversations between
* the current logged-in user and other users,
* you can call methods like UserService::queryRelatedUserIds(),
* UserService::queryFriends() to get all user IDs first,
* and pass these user IDs as targetIds to get all private conversations.
* * The returned PrivateConversation does NOT contain messages.
* To find messages in conversations, you can use methods like
* MessageService::queryMessages() and MessageService::queryMessagesWithTotal().
*
* @param targetIds the target user IDs.
* If empty, an empty list of conversations is returned.
* @return a list of private conversations.
* Note that the list only contains conversations in which the logged-in user is a participant.
* If the logged-in user is not a participant of a specified conversation,
* these conversations will be filtered out on the server, and no error will be thrown.
* @throws ResponseException if an error occurs.
*/
auto queryPrivateConversations(const std::unordered_set<int64_t>& targetIds)
-> boost::future<Response<std::vector<PrivateConversation>>>;

/**
* Find group conversations in which the logged-in user is a member.
*
* Common Scenarios:
* * If you want to find all group conversations between
* the current logged-in user and groups in which the logged-in user is a member,
* you can call methods like GroupService::queryJoinedGroupIds(),
* GroupService::queryJoinedGroupInfos() to get all group IDs first,
* and pass these group IDs as groupIds to get all group conversations.
* * GroupConversation does NOT contain messages.
* To find messages in conversations, you can use methods like
* MessageService::queryMessages() and MessageService::queryMessagesWithTotal().
*
* @param groupIds the target group IDs.
* If empty, an empty list of conversations is returned.
* @return a list of group conversations.
* Note that the list only contains conversations in which the logged-in user is a participant.
* If the logged-in user is not a participant of a specified conversation,
* these conversations will be filtered out on the server, and no error will be thrown.
* @throws ResponseException if an error occurs.
*/
auto queryGroupConversations(const std::unordered_set<int64_t>& groupIds)
-> boost::future<Response<std::vector<GroupConversation>>>;

/**
* Update the read date of the target private conversation.
*
* Common Scenarios:
* * To find the read date of a conversation actively (if no notification is received from the server),
* you can call queryPrivateConversations().
*
* Authorization:
* * If the server property `turms.service.conversation.read-receipt.enabled`
* is false (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateIsDisabled.
*
* Notifications:
* * If the server property `turms.service.notification.private-conversation-read-date-updated.notify-contact`
* is true (false by default),
* the server will send a read date update notification to the participant actively.
* * If the server property `turms.service.notification.private-conversation-read-date-updated.notify-requester-other-online-sessions`
* is true (true by default),
* the server will send a read date update notification to all other online sessions of the logged-in user actively.
*
* @param targetId the target user ID.
* @param readDate the read date.
* If null, the current time is used.
* @throws ResponseException if an error occurs.
*/
auto updatePrivateConversationReadDate(
int64_t targetId, const time_point& readDate = std::chrono::system_clock::now())
-> boost::future<Response<void>>;

/**
* Update the read date of the target group conversation.
*
* Common Scenarios:
* * To find the read date of a conversation actively (if no notification is received from the server),
* you can call queryGroupConversations().
*
* Authorization:
* * If the server property `turms.service.conversation.read-receipt.enabled`
* is false (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateIsDisabled.
* * If the target group doesn't exist, throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateOfNonexistentGroupConversation.
* * If the target group has disabled read receipts, throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateIsDisabledByGroup.
* * If the logged-in user is not a member of the target group, throws ResponseException with the code ResponseStatusCode::kNotGroupMemberToUpdateReadDateOfGroupConversation.
*
* Notifications:
* * If the server property `turms.service.notification.group-conversation-read-date-updated.notify-other-group-members`
* is true (false by default),
* the server will send a read date update notification to all participants actively.
* * If the server property `turms.service.notification.group-conversation-read-date-updated.notify-requester-other-online-sessions`
* is true (true by default),
* the server will send a read date update notification to all other online sessions of the logged-in user actively.
*
* @param groupId the target group ID.
* @param readDate the read date.
* If null, the current time is used.
* @throws ResponseException if an error occurs.
*/
auto updateGroupConversationReadDate(
int64_t groupId, const time_point& readDate = std::chrono::system_clock::now())
-> boost::future<Response<void>>;

/**
* Update the typing status of the target private conversation.
*
* Authorization:
* * If the server property `turms.service.conversation.typing-status.enabled`
* is true (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingTypingStatusIsDisabled.
* * If the logged-in user is not a friend of targetId, throws ResponseException with the code ResponseStatusCode::kNotFriendToSendTypingStatus.
*
* Notifications:
* * If the server property `turms.service.conversation.typing-status.enabled`
* is true (true by default),
* the server will send a typing status update notification to the participant actively.
*
* @param targetId the target user ID.
* @throws ResponseException if an error occurs.
*/
auto updatePrivateConversationTypingStatus(int64_t targetId) -> boost::future<Response<void>>;

/**
* Update the typing status of the target group conversation.
*
* Authorization:
* * If the server property `turms.service.conversation.typing-status.enabled`
* is true (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingTypingStatusIsDisabled.
* * If the logged-in user is not a member of the target group, throws ResponseException with the code ResponseStatusCode::kNotGroupMemberToSendTypingStatus.
*
* Notifications:
* * If the server property `turms.service.conversation.typing-status.enabled`
* is true (true by default),
* the server will send a typing status update notification to all participants actively.
*
* @param groupId the target group ID.
* @throws ResponseException if an error occurs.
*/
auto updateGroupConversationTypingStatus(int64_t groupId) -> boost::future<Response<void>>;

private:
Expand Down
Loading

0 comments on commit 5c0dce4

Please sign in to comment.