TIMSignalingManagerFunction.h 文件参考

类型定义
typedef void(*	TIMSignalingReceiveNewInvitationCallback) (const char *invite_id, const char *inviter, const char *group_id, const char *json_invitee_list, const char *data, const void *user_data)
typedef void(*	TIMSignalingInvitationCancelledCallback) (const char *invite_id, const char *inviter, const char *data, const void *user_data)
typedef void(*	TIMSignalingInviteeAcceptedCallback) (const char *invite_id, const char *invitee, const char *data, const void *user_data)
typedef void(*	TIMSignalingInviteeRejectedCallback) (const char *invite_id, const char *invitee, const char *data, const void *user_data)
typedef void(*	TIMSignalingInvitationTimeoutCallback) (const char *invite_id, const char *json_invitee_list, const void *user_data)
typedef void(*	TIMSignalingInvitationModifiedCallback) (const char *invite_id, const char *data, const void *user_data)

函数
TIM_API void	TIMSetSignalingReceiveNewInvitationCallback (TIMSignalingReceiveNewInvitationCallback cb, const void *user_data)
TIM_API void	TIMSetSignalingInvitationCancelledCallback (TIMSignalingInvitationCancelledCallback cb, const void *user_data)
TIM_API void	TIMSetSignalingInviteeAcceptedCallback (TIMSignalingInviteeAcceptedCallback cb, const void *user_data)
TIM_API void	TIMSetSignalingInviteeRejectedCallback (TIMSignalingInviteeRejectedCallback cb, const void *user_data)
TIM_API void	TIMSetSignalingInvitationTimeoutCallback (TIMSignalingInvitationTimeoutCallback cb, const void *user_data)
TIM_API void	TIMSetSignalingInvitationModifiedCallback (TIMSignalingInvitationModifiedCallback cb, const void *user_data)
TIM_API int	TIMSignalingInvite (const char *invitee, const char *data, bool online_user_only, const char *json_offline_push_info, int timeout, char *invite_id_buffer, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMSignalingInviteInGroup (const char *group_id, const char *json_invitee_array, const char *data, bool online_user_only, int timeout, char *invite_id_buffer, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMSignalingCancel (const char *invite_id, const char *data, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMSignalingAccept (const char *invite_id, const char *data, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMSignalingReject (const char *invite_id, const char *data, TIMCommCallback cb, const void *user_data)
TIM_API int	TIMGetSignalingInfo (const char *json_msg, TIMCommCallback json_signaling_info_cb, const void *user_data)
TIM_API int	TIMSignalingModifyInvitation (const char *invite_id, const char *data, TIMCommCallback cb, const void *user_data)

类型定义说明

TIMSignalingReceiveNewInvitationCallback

typedef void(* TIMSignalingReceiveNewInvitationCallback) (const char *invite_id, const char *inviter, const char *group_id, const char *json_invitee_list, const char *data, const void *user_data)

1.1 收到邀请的回调

参数

invite_id	邀请 ID
inviter	邀请者 userID
group_id	群组 ID
json_invitee_list	被邀请者 userID 列表，json 字符串类型
data	自定义字段
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMSignalingInvitationCancelledCallback

typedef void(* TIMSignalingInvitationCancelledCallback) (const char *invite_id, const char *inviter, const char *data, const void *user_data)

1.2 邀请被取消的回调

参数

invite_id	邀请 ID
inviter	邀请者 userID
data	自定义字段
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMSignalingInviteeAcceptedCallback

typedef void(* TIMSignalingInviteeAcceptedCallback) (const char *invite_id, const char *invitee, const char *data, const void *user_data)

1.3 被邀请者接受邀请的回调

参数

invite_id	邀请 ID
invitee	被邀请者 userID
data	自定义字段
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMSignalingInviteeRejectedCallback

typedef void(* TIMSignalingInviteeRejectedCallback) (const char *invite_id, const char *invitee, const char *data, const void *user_data)

1.4 被邀请者拒绝邀请的回调

参数

invite_id	邀请 ID
invitee	被邀请者 userID
data	自定义字段
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMSignalingInvitationTimeoutCallback

typedef void(* TIMSignalingInvitationTimeoutCallback) (const char *invite_id, const char *json_invitee_list, const void *user_data)

1.5 邀请超时的回调

参数

invite_id	邀请 ID
json_invitee_list	被邀请者 userID 列表，json 字符串类型
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

TIMSignalingInvitationModifiedCallback

typedef void(* TIMSignalingInvitationModifiedCallback) (const char *invite_id, const char *data, const void *user_data)

1.6 邀请被修改的回调（6.7 及其以上版本支持）

参数

invite_id	邀请 ID
data	自定义字段
user_data	ImSDK负责透传的用户自定义数据，未做任何处理

函数说明

TIMSetSignalingReceiveNewInvitationCallback()

TIM_API void TIMSetSignalingReceiveNewInvitationCallback	(	TIMSignalingReceiveNewInvitationCallback	cb,
		const void *	user_data
	)

2.1 设置收到信令邀请的回调

参数

cb	收到信令邀请的回调，请参考 TIMSignalingReceiveNewInvitationCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetSignalingInvitationCancelledCallback()

TIM_API void TIMSetSignalingInvitationCancelledCallback	(	TIMSignalingInvitationCancelledCallback	cb,
		const void *	user_data
	)

2.2 设置信令邀请被取消的回调

参数

cb	信令邀请被取消的回调，请参考 TIMSignalingInvitationCancelledCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetSignalingInviteeAcceptedCallback()

TIM_API void TIMSetSignalingInviteeAcceptedCallback	(	TIMSignalingInviteeAcceptedCallback	cb,
		const void *	user_data
	)

2.3 设置信令邀请被接收者同意的回调

参数

cb	同意信令邀请的回调，请参考 TIMSignalingInviteeAcceptedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetSignalingInviteeRejectedCallback()

TIM_API void TIMSetSignalingInviteeRejectedCallback	(	TIMSignalingInviteeRejectedCallback	cb,
		const void *	user_data
	)

2.4 设置信令邀请被接收者拒绝的回调

参数

cb	拒绝信令邀请的回调，请参考 TIMSignalingInviteeRejectedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetSignalingInvitationTimeoutCallback()

TIM_API void TIMSetSignalingInvitationTimeoutCallback	(	TIMSignalingInvitationTimeoutCallback	cb,
		const void *	user_data
	)

2.5 设置信令邀请超时的回调

参数

cb	信令邀请超时的回调，请参考 TIMSignalingInvitationTimeoutCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSetSignalingInvitationModifiedCallback()

TIM_API void TIMSetSignalingInvitationModifiedCallback	(	TIMSignalingInvitationModifiedCallback	cb,
		const void *	user_data
	)

2.6 设置信令邀请被修改的回调

参数

cb	信令邀请被修改的回调，请参考 TIMSignalingInvitationModifiedCallback
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

TIMSignalingInvite()

TIM_API int TIMSignalingInvite	(	const char *	invitee,
		const char *	data,
		bool	online_user_only,
		const char *	json_offline_push_info,
		int	timeout,
		char *	invite_id_buffer,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.1 邀请某个人

参数

invitee	被邀请人的 userID
data	自定义数据
online_user_only	是否只有在线用户才能收到邀请，如果设置为 true，只有在线用户才能收到，并且 invite 操作也不会产生历史消息（针对该次 invite 的后续 cancel、accept、reject、timeout 操作也同样不会产生历史消息）
json_offline_push_info	离线推送时携带的标题和声音，其中 desc 为必填字段，推送的时候会默认展示 desc 信息，Json key 的定义请参考 OfflinePushConfig
timeout	超时时间，单位 s，如果设置为 0，SDK 不会做超时检测，也不触发 TIMSignalingInvitationTimeoutCallback 回调
invite_id_buffer	出参，邀请 ID，分配内存大小不能低于 128 字节，如果不需要，可传入 nullptr，调用接口后，可以读取到以 '\0' 结尾的字符串
cb	回调
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

 Json::Value json_offline_push_info;
 json_offline_push_info[kTIMOfflinePushConfigDesc] = "push desc";

const size_t kMessageIDLength = 128;
char invite_id_buffer[kMessageIDLength] = {0};
int ret = TIMSignalingInvite("user", "custom data", true, json_offline_push_info, 30, invite_id_buffer,
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 邀请成功
                     } else {
                          // 邀请失败
                      }
              }, nullptr);

TIMSignalingInviteInGroup()

TIM_API int TIMSignalingInviteInGroup	(	const char *	group_id,
		const char *	json_invitee_array,
		const char *	data,
		bool	online_user_only,
		int	timeout,
		char *	invite_id_buffer,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.2 邀请群内的某些人

参数

group_id	发起邀请所在群组
json_invitee_array	被邀请人列表，且被邀请人必须已经在群组内，否则邀请无效
data	自定义字段
online_user_only	是否只有在线用户才能收到邀请，如果设置为 true，只有在线用户才能收到，并且 invite 操作也不会产生历史消息（针对该次 invite 的后续 cancel、accept、reject、timeout 操作也同样不会产生历史消息）
timeout	超时时间，单位 s，如果设置为 0，SDK 不会做超时检测，也不触发 TIMSignalingInvitationTimeoutCallback 回调
invite_id_buffer	出参，邀请ID，分配内存大小不能低于 128 字节，如果不需要，可传入 nullptr，调用接口后，可以读取到以 '\0' 结尾的字符串
cb	回调
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

示例

Json::Value json_invitee_array(Json::arrayValue);
json_invitee_array.append("user1");
json_invitee_array.append("user2");

const size_t kMessageIDLength = 128;
char invite_id_buffer[kMessageIDLength] = {0};
int ret = TIMSignalingInviteInGroup("group_id", json_invitee_array, "custom data", true, 30, invite_id_buffer,
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 邀请成功
                     } else {
                          // 邀请失败
                      }
              }, nullptr);

TIMSignalingCancel()

TIM_API int TIMSignalingCancel	(	const char *	invite_id,
		const char *	data,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.3 邀请方取消邀请

参数

invite_id	邀请 ID
data	自定义字段
cb	回调
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

如果所有被邀请人都已经处理了当前邀请（包含超时），不能再取消当前邀请。

示例

const char *invite_id = "XXX-XXX-XXX-XXX";
int ret = TIMSignalingCancel(invite_id, "",
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 取消成功
                     } else {
                          // 取消失败
                      }
              }, nullptr);

TIMSignalingAccept()

TIM_API int TIMSignalingAccept	(	const char *	invite_id,
		const char *	data,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.4 被邀请方接受邀请

参数

invite_id	邀请 ID
data	自定义字段
cb	回调
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

不能接受不是针对自己的邀请，请在收到 TIMSignalingReceiveNewInvitation 回调的时候先判断 json_invitee_array 有没有自己，如果没有自己，不能 accept 邀请。

示例

const char *invite_id = "XXX-XXX-XXX-XXX";
int ret = TIMSignalingAccept(invite_id, "",
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 接受邀请成功
                     } else {
                          // 接受邀请失败
                      }
              }, nullptr);

TIMSignalingReject()

TIM_API int TIMSignalingReject	(	const char *	invite_id,
		const char *	data,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.5 被邀请方拒绝邀请

参数

invite_id	邀请 ID
data	自定义字段
cb	回调
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

不能拒绝不是针对自己的邀请，请在收到 TIMSignalingReceiveNewInvitation 回调的时候先判断 json_invitee_array 有没有自己，如果没有自己，不能 reject 邀请。

示例

const char *invite_id = "XXX-XXX-XXX-XXX";
int ret = TIMSignalingReject(invite_id, "",
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 拒绝邀请成功
                     } else {
                          // 拒绝邀请失败
                      }
              }, nullptr);

TIMGetSignalingInfo()

TIM_API int TIMGetSignalingInfo	(	const char *	json_msg,
		TIMCommCallback	json_signaling_info_cb,
		const void *	user_data
	)

3.6 获取信令信息

参数

json_msg	消息 json 字符串
json_signaling_info_cb	获取信令消息的回调，您可以在该回调中根据 code == ERR_SUCC 来确定当前 json_msg 为信令消息
user_data	用户自定义数据，ImSDK只负责传回给回调函数cb，不做任何处理

返回

int 返回TIM_SUCC表示接口调用成功（接口只有返回TIM_SUCC，回调cb才会被调用），其他值表示接口调用失败。每个返回值的定义请参考 TIMResult

注意

如果 invite 设置 online_user_only 为 false，每次信令操作（包括 invite、cancel、accept、reject、timeout）都会产生一条自定义消息，该消息会通过 TIMRecvNewMsgCallback 抛给用户，用户也可以通过历史消息拉取，如果需要根据信令信息做自定义化文本展示，可以调用下面接口获取信令信息。

示例

const char *json_msg = "";
int ret = TIMGetSignalingInfo(json_msg,
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 当前消息是信令消息
                     } else {
                          // 当前消息为普通消息
                      }
              }, nullptr);

TIMSignalingModifyInvitation()

TIM_API int TIMSignalingModifyInvitation	(	const char *	invite_id,
		const char *	data,
		TIMCommCallback	cb,
		const void *	user_data
	)

3.7 修改邀请信令（6.7 及其以上版本支持）

注意

仅支持修改邀请信令的自定义字段 data。只有在线用户才能收到的邀请信令不能被修改。

示例

const char *invite_id = "XXX-XXX-XXX-XXX";
int ret = TIMSignalingModifyInvitation(invite_id, "",
                     [](int32_t code, const char* desc, const char* json_params, const void* user_data){
                     if (ERR_SUCC == code) {
                          // 修改邀请成功
                     } else {
                          // 修改邀请失败
                      }
              }, nullptr);