Skip to content

Commit 279a915

Browse files
JamesChenXJamesChenX
committed
1. Add detailed docs on each service API for all clients
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
1 parent c55fdc2 commit 279a915

35 files changed

+7797
-256
lines changed

‎turms-client-cpp/include/turms/client/model/response_status_code.h‎

Lines changed: 69 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -100,21 +100,25 @@ const int kQueryingNearestUsersBySessionIdIsDisabled = 2201;
100100

101101
// User - Info
102102
const int kUpdateInfoOfNonexistentUser = 2300;
103-
const int kUserProfileNotFound = 2301;
104-
const int kProfileRequesterNotInContactsOrBlocked = 2302;
105-
const int kProfileRequesterHasBeenBlocked = 2303;
103+
const int kNotFriendToQueryUserProfile = 2301;
104+
const int kBlockedUserToQueryUserProfile = 2302;
106105

107106
// User - Permission
108107
const int kQueryPermissionOfNonexistentUser = 2400;
109108

110109
// User - Relationship
111110
const int kAddNonRelatedUserToGroup = 2500;
112111
const int kCreateExistingRelationship = 2501;
112+
const int kCannotBlockOneself = 2502;
113113

114114
// User - Friend Request
115-
const int kRequesterNotFriendRequestRecipient = 2600;
116-
const int kCreateExistingFriendRequest = 2601;
117-
const int kFriendRequestSenderHasBeenBlocked = 2602;
115+
const int kCreateExistingFriendRequest = 2600;
116+
const int kBlockedUserToSendFriendRequest = 2601;
117+
const int kRecallNonPendingFriendRequest = 2602;
118+
const int kRecallingFriendRequestIsDisabled = 2603;
119+
const int kNotSenderToRecallFriendRequest = 2604;
120+
const int kUpdateNonPendingFriendRequest = 2605;
121+
const int kNotRecipientToUpdateFriendRequest = 2606;
118122

119123
// Group
120124

@@ -127,21 +131,25 @@ const int kNotGroupMemberToUpdateGroupInfo = 3003;
127131
// Group - Type
128132
const int kNoPermissionToCreateGroupWithGroupType = 3100;
129133
const int kCreateGroupWithNonexistentGroupType = 3101;
134+
const int kUpdatingGroupTypeIsDisabled = 3102;
135+
const int kNotGroupOwnerToUpdateGroupType = 3103;
136+
const int kNoPermissionToUpdateGroupToGroupType = 3104;
137+
const int kUpdateGroupToNonexistentGroupType = 3105;
130138

131139
// Group - Ownership
132140
const int kNotActiveUserToCreateGroup = 3200;
133141
const int kNotGroupOwnerToTransferGroup = 3201;
134142
const int kNotGroupOwnerToDeleteGroup = 3202;
135-
const int kSuccessorNotGroupMember = 3203;
136-
const int kOwnerQuitsWithoutSpecifyingSuccessor = 3204;
143+
const int kGroupSuccessorNotGroupMember = 3203;
144+
const int kGroupOwnerQuitWithoutSpecifyingSuccessor = 3204;
137145
const int kMaxOwnedGroupsReached = 3205;
138146
const int kTransferNonexistentGroup = 3206;
139147

140148
// Group - Question
141149
const int kNotGroupOwnerOrManagerToCreateGroupQuestion = 3300;
142150
const int kNotGroupOwnerOrManagerToDeleteGroupQuestion = 3301;
143151
const int kNotGroupOwnerOrManagerToUpdateGroupQuestion = 3302;
144-
const int kNotGroupOwnerOrManagerToAccessGroupQuestionAnswer = 3303;
152+
const int kNotGroupOwnerOrManagerToQueryGroupQuestionAnswer = 3303;
145153
const int kCreateGroupQuestionForInactiveGroup = 3304;
146154
const int kCreateGroupQuestionForGroupUsingJoinRequest = 3305;
147155
const int kCreateGroupQuestionForGroupUsingInvitation = 3306;
@@ -152,54 +160,64 @@ const int kAnswerInactiveGroupQuestion = 3310;
152160
const int kAnswerGroupQuestionOfInactiveGroup = 3311;
153161

154162
// Group - Member
155-
const int kAddUserToGroupRequiringInvitation = 3400;
163+
const int kAddUserToGroupRequiringUsersApproval = 3400;
156164
const int kAddUserToInactiveGroup = 3401;
157-
const int kAddUserToGroupWithRoleHigherThanRequester = 3402;
165+
const int kNotGroupOwnerToAddGroupManager = 3402;
158166
const int kAddUserToGroupWithSizeLimitReached = 3403;
159167
const int kAddBlockedUserToGroup = 3404;
160-
const int kAddBlockedUserToInactiveGroup = 3405;
161-
const int kNotGroupOwnerOrManagerToRemoveGroupMember = 3406;
162-
const int kNotGroupOwnerToRemoveGroupOwnerOrManager = 3407;
163-
const int kNotGroupOwnerToUpdateGroupMemberRole = 3408;
164-
const int kUpdateGroupMemberRoleOfNonexistentGroup = 3409;
165-
const int kNotGroupOwnerToUpdateGroupMemberInfo = 3410;
166-
const int kNotGroupOwnerOrManagerToUpdateGroupMemberInfo = 3411;
167-
const int kNotGroupMemberToUpdateGroupMemberInfo = 3412;
168-
const int kUpdateGroupMemberInfoOfNonexistentGroup = 3413;
169-
const int kUpdateInfoOfNonexistentGroupMember = 3414;
170-
const int kNotGroupOwnerOrManagerToMuteGroupMember = 3415;
171-
const int kMuteGroupMemberWithRoleEqualToOrHigherThanRequester = 3416;
172-
const int kMuteGroupMemberOfNonexistentGroup = 3417;
173-
const int kMuteNonexistentGroupMember = 3418;
174-
const int kNotGroupMemberToQueryGroupMemberInfo = 3419;
168+
const int kNotGroupOwnerToAddGroupMember = 3405;
169+
const int kNotGroupOwnerOrManagerToAddGroupMember = 3406;
170+
const int kNotGroupMemberToAddGroupMember = 3407;
171+
const int kNotGroupOwnerOrManagerToRemoveGroupMember = 3408;
172+
const int kNotGroupOwnerToRemoveGroupOwnerOrManager = 3409;
173+
const int kNotGroupOwnerToUpdateGroupMemberRole = 3410;
174+
const int kUpdateGroupMemberRoleOfNonexistentGroup = 3411;
175+
const int kNotGroupOwnerToUpdateGroupMemberInfo = 3412;
176+
const int kNotGroupOwnerOrManagerToUpdateGroupMemberInfo = 3413;
177+
const int kNotGroupMemberToUpdateGroupMemberInfo = 3414;
178+
const int kUpdateGroupMemberInfoOfNonexistentGroup = 3415;
179+
const int kUpdateInfoOfNonexistentGroupMember = 3416;
180+
const int kNotGroupOwnerOrManagerToMuteGroupMember = 3417;
181+
const int kMuteGroupMemberWithRoleEqualToOrHigherThanRequester = 3418;
182+
const int kMuteGroupMemberOfNonexistentGroup = 3419;
183+
const int kMuteNonexistentGroupMember = 3420;
184+
const int kNotGroupMemberToQueryGroupMemberInfo = 3421;
185+
const int kUserJoinGroupWithoutAcceptingGroupInvitation = 3422;
186+
const int kUserJoinGroupWithoutAnsweringGroupQuestion = 3423;
187+
const int kUserJoinGroupWithoutSendingGroupJoinRequest = 3424;
175188

176189
// Group - Blocklist
177190
const int kNotGroupOwnerOrManagerToAddBlockedUser = 3500;
178191
const int kNotGroupOwnerOrManagerToRemoveBlockedUser = 3501;
179192

180193
// Group - Join Request
181-
const int kGroupJoinRequestSenderHasBeenBlocked = 3600;
182-
const int kNotGroupJoinRequestSenderToRecallRequest = 3601;
183-
const int kNotGroupOwnerOrManagerToAccessGroupJoinRequest = 3602;
184-
const int kRecallNonPendingGroupJoinRequest = 3603;
185-
const int kSendGroupJoinRequestToInactiveGroup = 3604;
186-
const int kSendGroupJoinRequestToGroupUsingMembershipRequest = 3605;
187-
const int kSendGroupJoinRequestToGroupUsingInvitation = 3606;
188-
const int kSendGroupJoinRequestToGroupUsingQuestion = 3607;
189-
const int kRecallingGroupJoinRequestIsDisabled = 3608;
194+
const int kBlockedUserSendGroupJoinRequest = 3600;
195+
const int kGroupMemberSendGroupJoinRequest = 3601;
196+
const int kNotSenderToRecallGroupJoinRequest = 3602;
197+
const int kNotGroupOwnerOrManagerToQueryGroupJoinRequest = 3603;
198+
const int kRecallNonPendingGroupJoinRequest = 3604;
199+
const int kSendGroupJoinRequestToInactiveGroup = 3605;
200+
const int kSendGroupJoinRequestToGroupUsingMembershipRequest = 3606;
201+
const int kSendGroupJoinRequestToGroupUsingInvitation = 3607;
202+
const int kSendGroupJoinRequestToGroupUsingQuestion = 3608;
203+
const int kRecallingGroupJoinRequestIsDisabled = 3609;
204+
const int kUpdateNonPendingGroupJoinRequest = 3610;
205+
const int kNotGroupOwnerOrManagerToUpdateGroupJoinRequest = 3611;
190206

191207
// Group - Invitation
192-
const int kGroupInviterNotGroupMember = 3700;
193-
const int kGroupInviteeAlreadyGroupMember = 3701;
194-
const int kGroupInviteeHasBeenBlockedByGroup = 3702;
195-
const int kNotGroupOwnerOrManagerToRecallGroupInvitation = 3703;
196-
const int kNotGroupOwnerOrManagerToAccessGroupInvitation = 3704;
197-
const int kNotGroupOwnerToSendGroupInvitation = 3705;
198-
const int kNotGroupOwnerOrManagerToSendGroupInvitation = 3706;
199-
const int kNotGroupMemberToSendGroupInvitation = 3707;
200-
const int kRecallingGroupInvitationIsDisabled = 3708;
201-
const int kSendGroupInvitationToGroupNotRequireInvitation = 3709;
202-
const int kRecallNonPendingGroupInvitation = 3710;
208+
const int kSendGroupInvitationToGroupMember = 3700;
209+
const int kSendGroupInvitationToBlockedUser = 3701;
210+
const int kSendGroupInvitationToGroupNotRequiringUsersApproval = 3702;
211+
const int kNotGroupOwnerToSendGroupInvitation = 3703;
212+
const int kNotGroupOwnerOrManagerToSendGroupInvitation = 3704;
213+
const int kNotGroupMemberToSendGroupInvitation = 3705;
214+
const int kRecallingGroupInvitationIsDisabled = 3706;
215+
const int kNotGroupOwnerOrManagerToRecallGroupInvitation = 3707;
216+
const int kNotGroupOwnerOrManagerOrSenderToRecallGroupInvitation = 3708;
217+
const int kRecallNonPendingGroupInvitation = 3709;
218+
const int kUpdateNonPendingGroupInvitation = 3710;
219+
const int kNotInviteeToUpdateGroupInvitation = 3711;
220+
const int kNotGroupOwnerOrManagerToQueryGroupInvitation = 3712;
203221

204222
// Conversation
205223

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

220238
// Message - Send
221239
const int kMessageRecipientNotActive = 5000;
222-
const int kMessageSenderNotInContactsOrBlocked = 5001;
223-
const int kPrivateMessageSenderHasBeenBlocked = 5002;
224-
const int kGroupMessageSenderHasBeenBlocked = 5003;
240+
const int kNotFriendToSendPrivateMessage = 5001;
241+
const int kBlockedUserSendPrivateMessage = 5002;
242+
const int kBlockedUserSendGroupMessage = 5003;
225243
const int kSendMessageToInactiveGroup = 5004;
226244
const int kSendMessageToMutedGroup = 5005;
227245
const int kSendMessageToNonexistentGroup = 5006;
228246
const int kSendingMessagesToOneselfIsDisabled = 5007;
229247
const int kMutedGroupMemberSendMessage = 5008;
230-
const int kGuestsHaveBeenMuted = 5009;
248+
const int kNotSpeakableGroupGuestToSendMessage = 5009;
231249
const int kMessageIsIllegal = 5010;
250+
const int kNotMessageRecipientOrSenderToForwardMessage = 5011;
232251

233252
// Message - Update
234253
const int kUpdatingMessageBySenderIsDisabled = 5100;

‎turms-client-cpp/include/turms/client/service/conversation_service.h‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ namespace service {
2020
class ConversationService : private boost::noncopyable {
2121
private:
2222
using time_point = std::chrono::time_point<std::chrono::system_clock>;
23+
using ResponseException = exception::ResponseException;
2324

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

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

61+
/**
62+
* Find group conversations in which the logged-in user is a member.
63+
*
64+
* Common Scenarios:
65+
* * If you want to find all group conversations between
66+
* the current logged-in user and groups in which the logged-in user is a member,
67+
* you can call methods like GroupService::queryJoinedGroupIds(),
68+
* GroupService::queryJoinedGroupInfos() to get all group IDs first,
69+
* and pass these group IDs as groupIds to get all group conversations.
70+
* * GroupConversation does NOT contain messages.
71+
* To find messages in conversations, you can use methods like
72+
* MessageService::queryMessages() and MessageService::queryMessagesWithTotal().
73+
*
74+
* @param groupIds the target group IDs.
75+
* If empty, an empty list of conversations is returned.
76+
* @return a list of group conversations.
77+
* Note that the list only contains conversations in which the logged-in user is a participant.
78+
* If the logged-in user is not a participant of a specified conversation,
79+
* these conversations will be filtered out on the server, and no error will be thrown.
80+
* @throws ResponseException if an error occurs.
81+
*/
3982
auto queryGroupConversations(const std::unordered_set<int64_t>& groupIds)
4083
-> boost::future<Response<std::vector<GroupConversation>>>;
4184

85+
/**
86+
* Update the read date of the target private conversation.
87+
*
88+
* Common Scenarios:
89+
* * To find the read date of a conversation actively (if no notification is received from the server),
90+
* you can call queryPrivateConversations().
91+
*
92+
* Authorization:
93+
* * If the server property `turms.service.conversation.read-receipt.enabled`
94+
* is false (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateIsDisabled.
95+
*
96+
* Notifications:
97+
* * If the server property `turms.service.notification.private-conversation-read-date-updated.notify-contact`
98+
* is true (false by default),
99+
* the server will send a read date update notification to the participant actively.
100+
* * If the server property `turms.service.notification.private-conversation-read-date-updated.notify-requester-other-online-sessions`
101+
* is true (true by default),
102+
* the server will send a read date update notification to all other online sessions of the logged-in user actively.
103+
*
104+
* @param targetId the target user ID.
105+
* @param readDate the read date.
106+
* If null, the current time is used.
107+
* @throws ResponseException if an error occurs.
108+
*/
42109
auto updatePrivateConversationReadDate(
43110
int64_t targetId, const time_point& readDate = std::chrono::system_clock::now())
44111
-> boost::future<Response<void>>;
45112

113+
/**
114+
* Update the read date of the target group conversation.
115+
*
116+
* Common Scenarios:
117+
* * To find the read date of a conversation actively (if no notification is received from the server),
118+
* you can call queryGroupConversations().
119+
*
120+
* Authorization:
121+
* * If the server property `turms.service.conversation.read-receipt.enabled`
122+
* is false (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateIsDisabled.
123+
* * If the target group doesn't exist, throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateOfNonexistentGroupConversation.
124+
* * If the target group has disabled read receipts, throws ResponseException with the code ResponseStatusCode::kUpdatingReadDateIsDisabledByGroup.
125+
* * If the logged-in user is not a member of the target group, throws ResponseException with the code ResponseStatusCode::kNotGroupMemberToUpdateReadDateOfGroupConversation.
126+
*
127+
* Notifications:
128+
* * If the server property `turms.service.notification.group-conversation-read-date-updated.notify-other-group-members`
129+
* is true (false by default),
130+
* the server will send a read date update notification to all participants actively.
131+
* * If the server property `turms.service.notification.group-conversation-read-date-updated.notify-requester-other-online-sessions`
132+
* is true (true by default),
133+
* the server will send a read date update notification to all other online sessions of the logged-in user actively.
134+
*
135+
* @param groupId the target group ID.
136+
* @param readDate the read date.
137+
* If null, the current time is used.
138+
* @throws ResponseException if an error occurs.
139+
*/
46140
auto updateGroupConversationReadDate(
47141
int64_t groupId, const time_point& readDate = std::chrono::system_clock::now())
48142
-> boost::future<Response<void>>;
49143

144+
/**
145+
* Update the typing status of the target private conversation.
146+
*
147+
* Authorization:
148+
* * If the server property `turms.service.conversation.typing-status.enabled`
149+
* is true (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingTypingStatusIsDisabled.
150+
* * If the logged-in user is not a friend of targetId, throws ResponseException with the code ResponseStatusCode::kNotFriendToSendTypingStatus.
151+
*
152+
* Notifications:
153+
* * If the server property `turms.service.conversation.typing-status.enabled`
154+
* is true (true by default),
155+
* the server will send a typing status update notification to the participant actively.
156+
*
157+
* @param targetId the target user ID.
158+
* @throws ResponseException if an error occurs.
159+
*/
50160
auto updatePrivateConversationTypingStatus(int64_t targetId) -> boost::future<Response<void>>;
51161

162+
/**
163+
* Update the typing status of the target group conversation.
164+
*
165+
* Authorization:
166+
* * If the server property `turms.service.conversation.typing-status.enabled`
167+
* is true (true by default), throws ResponseException with the code ResponseStatusCode::kUpdatingTypingStatusIsDisabled.
168+
* * If the logged-in user is not a member of the target group, throws ResponseException with the code ResponseStatusCode::kNotGroupMemberToSendTypingStatus.
169+
*
170+
* Notifications:
171+
* * If the server property `turms.service.conversation.typing-status.enabled`
172+
* is true (true by default),
173+
* the server will send a typing status update notification to all participants actively.
174+
*
175+
* @param groupId the target group ID.
176+
* @throws ResponseException if an error occurs.
177+
*/
52178
auto updateGroupConversationTypingStatus(int64_t groupId) -> boost::future<Response<void>>;
53179

54180
private:

0 commit comments

Comments
 (0)