Roomの検索・作成・参加とイベントハンドラの登録。 [詳解]

#include <stdint.h>
#include "member.h"
#include "publication.h"
#include "subscription.h"

データ構造
struct	skw_room_data_field_t
	Roomの取得/作成結果を受け取る出力先。NULLを設定したフィールドには格納されない。 [詳解]
struct	skw_room_handlers_t
	Roomの各イベント通知を受け取るハンドラ。不要なイベントのフィールドはNULLにできる。 [詳解]
struct	skw_room_create_params_t
	skw_room_createのパラメータ。 [詳解]
struct	skw_room_find_by_id_params_t
	skw_room_find_by_idのパラメータ。 [詳解]
struct	skw_room_find_by_name_params_t
	skw_room_find_by_nameのパラメータ。 [詳解]
struct	skw_room_find_or_create_params_t
	skw_room_find_or_createのパラメータ。 [詳解]
struct	skw_room_update_metadata_params_t
	skw_room_update_metadataのパラメータ。 [詳解]
struct	skw_room_join_params_t
	skw_room_joinのパラメータ。 [詳解]

マクロ定義
#define	SKW_ROOM_ID_SIZE (36+1)
	RoomIDを格納するバッファのサイズ（NUL終端を含む）。
#define	SKW_ROOM_NAME_SIZE (128+1)
	RoomNameを格納するバッファのサイズ（NUL終端を含む）。
#define	SKW_ROOM_METADATA_SIZE (1024+1)
	RoomMetadataを格納するバッファのサイズ（NUL終端を含む）。
#define	SKW_ROOM_REMOTE_MEMBER_COUNT (2)
	同時に接続できるRemoteMemberの数の上限。
#define	SKW_ROOM_PERSON_COUNT (1 + SKW_ROOM_REMOTE_MEMBER_COUNT)
	Roomに居るMemberの数。自分と相手の合計。
#define	SKW_ROOM_BOT_COUNT (1)
	Roomで想定するBotの数。SDKはSFUを使わないが、Roomの取得結果にはMemberとして現れるため枠だけ確保する。
#define	SKW_ROOM_DATA_PUBLICATION_COUNT (2)
	PublishできるDataStreamの本数。Video・Audioは各1本で固定。
#define	SKW_ROOM_DATA_SUBSCRIPTION_COUNT (2)
	相手Member1人からSubscribeできるDataStreamの本数。相手は自分より多くのDataをPublishし得るため、 Publishする本数とは別に決める。
#define	SKW_ROOM_MEMBER_DATA_COUNT (2)
	1Memberが持ちうるDataStreamの本数。
#define	SKW_ROOM_MEMBER_PUBLICATION_COUNT (1 + 1 + SKW_ROOM_MEMBER_DATA_COUNT)
	1MemberがPublishできるStreamの数。Video 1・Audio 1・Data。
#define	SKW_ROOM_CAPACITY_MEMBERS (SKW_ROOM_PERSON_COUNT + SKW_ROOM_BOT_COUNT)
	Roomの取得結果として格納できるMember数の上限。Person MemberとSFU Botの合計。
#define	SKW_ROOM_CAPACITY_PUBLICATIONS (SKW_ROOM_PERSON_COUNT * SKW_ROOM_MEMBER_PUBLICATION_COUNT)
	Roomの取得結果として格納できるPublication数の上限。全Person MemberがPublishできる本数の合計。
#define	SKW_ROOM_CAPACITY_SUBSCRIPTIONS (SKW_ROOM_PERSON_COUNT * SKW_ROOM_REMOTE_MEMBER_COUNT * SKW_ROOM_MEMBER_PUBLICATION_COUNT)
	Roomの取得結果として格納できるSubscription数の上限。各Person Memberが自分以外のPublicationをすべてSubscribeした場合の合計。
#define	SKW_ROOM_JOIN_TTL_SEC_DEFAULT (30U)
	skw_room_joinでttl_secを指定しなかった場合に使うMemberの有効期間（秒）。
#define	SKW_ROOM_CAPACITY_EXHAUSTED_MEMBERS (1u << 0)
	Member数が上限を超過したことを示すビット。
#define	SKW_ROOM_CAPACITY_EXHAUSTED_PUBLICATIONS (1u << 1)
	Publication数が上限を超過したことを示すビット。
#define	SKW_ROOM_CAPACITY_EXHAUSTED_SUBSCRIPTIONS (1u << 2)
	Subscription数が上限を超過したことを示すビット。
#define	SKW_ROOM_CREATE_PARAMS_INIT(...)
	skw_room_create_params_tの初期化子。指定しなかったフィールドには既定値が入ります。
#define	SKW_ROOM_FIND_BY_ID_PARAMS_INIT(...)
	skw_room_find_by_id_params_tの初期化子。指定しなかったフィールドには既定値が入ります。
#define	SKW_ROOM_FIND_BY_NAME_PARAMS_INIT(...)
	skw_room_find_by_name_params_tの初期化子。指定しなかったフィールドには既定値が入ります。
#define	SKW_ROOM_FIND_OR_CREATE_PARAMS_INIT(...)
	skw_room_find_or_create_params_tの初期化子。指定しなかったフィールドには既定値が入ります。
#define	SKW_ROOM_UPDATE_METADATA_PARAMS_INIT(...)
	skw_room_update_metadata_params_tの初期化子。指定しなかったフィールドには既定値が入ります。
#define	SKW_ROOM_JOIN_PARAMS_INIT(...)
	skw_room_join_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

型定義
typedef char	skw_room_id_t[SKW_ROOM_ID_SIZE]
	RoomIDを格納する文字列型（NUL終端を含む）。
typedef char	skw_room_name_t[SKW_ROOM_NAME_SIZE]
	RoomNameを格納する文字列型（NUL終端を含む）。
typedef char	skw_room_metadata_t[SKW_ROOM_METADATA_SIZE]
	RoomMetadataを格納する文字列型（NUL終端を含む）。
typedef skw_room_member_data_field_t	skw_room_member_data_fields_t[SKW_ROOM_CAPACITY_MEMBERS]
	複数のMemberの取得結果を受け取る出力先の配列型。
typedef skw_room_publication_data_field_t	skw_room_publication_data_fields_t[SKW_ROOM_CAPACITY_PUBLICATIONS]
	複数のPublicationの取得結果を受け取る出力先の配列型。
typedef skw_room_subscription_data_field_t	skw_room_subscription_data_fields_t[SKW_ROOM_CAPACITY_SUBSCRIPTIONS]
	複数のSubscriptionの取得結果を受け取る出力先の配列型。
typedef uint32_t	skw_room_capacity_exhaustion_flags_t
	各リソースの上限超過をビットで示すフラグ。
typedef void(*	skw_room_on_room_closed_t) (const char *room_id)
	Roomが削除されたときに呼ばれます。
typedef void(*	skw_room_on_room_metadata_updated_t) (const char room_id, const char metadata)
	RoomのMetadataが更新されたときに呼ばれます。
typedef void(*	skw_room_on_member_joined_t) (const char room_id, const char member_id)
	Memberが参加したときに呼ばれます。
typedef void(*	skw_room_on_member_left_t) (const char room_id, const char member_id)
	Memberが退出したときに呼ばれます。
typedef void(*	skw_room_on_member_metadata_updated_t) (const char room_id, const char member_id, const char *metadata)
	MemberのMetadataが更新されたときに呼ばれます。
typedef void(*	skw_room_on_stream_published_t) (const char room_id, const char publication_id, const char *publisher_id, skw_room_publication_content_type_t content_type)
	StreamがPublishされたときに呼ばれます。
typedef void(*	skw_room_on_stream_unpublished_t) (const char room_id, const char publication_id, const char *publisher_id)
	StreamがUnpublishされたときに呼ばれます。
typedef void(*	skw_room_on_publication_subscribed_t) (const char room_id, const char subscription_id, const char *member_id)
	PublicationがSubscribeされたときに呼ばれます。
typedef void(*	skw_room_on_publication_unsubscribed_t) (const char room_id, const char subscription_id, const char *member_id)
	PublicationがUnsubscribeされたときに呼ばれます。
typedef void(*	skw_room_on_publication_metadata_updated_t) (const char room_id, const char publication_id, const char *metadata)
	PublicationのMetadataが更新されたときに呼ばれます。
typedef struct skw_room_handlers_t	skw_room_handlers_t
	Roomの各イベント通知を受け取るハンドラ。不要なイベントのフィールドはNULLにできる。

列挙型
enum	skw_room_err_t { SKW_ROOM_OK = 0 , SKW_ROOM_ERR_NULL_ARGS = 1 , SKW_ROOM_ERR_INVALID_ARGS = 2 , SKW_ROOM_ERR_CONTEXT_NOT_INITED = 3 , SKW_ROOM_ERR_CONTEXT_NOT_SETUP = 4 , SKW_ROOM_ERR_REQUEST_FAILED = 5 , SKW_ROOM_ERR_MUTEX_UNLOCK_FAILED = 6 , SKW_ROOM_ERR_CALLED_IN_HANDLER = 7 , SKW_ROOM_ERR_CAPACITY_EXHAUSTED = 8 , SKW_ROOM_ERR_SEND_FAILED = 9 , SKW_ROOM_ERR_TIMEOUT = 10 , SKW_ROOM_ERR_CONNECTION_CLOSED = 11 , SKW_ROOM_ERR_RESPONSE_TOO_LARGE = 12 , SKW_ROOM_ERR_RESPONSE_PARSE_FAILED = 13 , SKW_ROOM_ERR_CONNECTION_FAILED = 14 , SKW_ROOM_ERR_ALREADY_JOINED = 15 , SKW_ROOM_ERR_UNKNOWN = 99 , SKW_ROOM_ERR_BAD_REQUEST = 400 , SKW_ROOM_ERR_UNAUTHORIZED = 401 , SKW_ROOM_ERR_FORBIDDEN = 403 , SKW_ROOM_ERR_NOT_FOUND = 404 , SKW_ROOM_ERR_ALREADY_EXIST = 409 , SKW_ROOM_ERR_TOO_LARGE = 413 , SKW_ROOM_ERR_TOO_MANY_REQUESTS = 429 , SKW_ROOM_ERR_SERVER_INTERNAL = 500 , SKW_ROOM_ERR_SERVER_BUSY = 503 }
	Room APIのエラーコード。 [詳解]

関数
skw_room_err_t	skw_room_create (const skw_room_create_params_t params, skw_room_data_field_t data_fields)
	指定したパラメータでRoomを新規作成します。
skw_room_err_t	skw_room_find_by_id (const skw_room_find_by_id_params_t params, skw_room_data_field_t data_fields)
	IDでRoomを検索します。
skw_room_err_t	skw_room_find_by_name (const skw_room_find_by_name_params_t params, skw_room_data_field_t data_fields)
	NameでRoomを検索します。
skw_room_err_t	skw_room_find_or_create (const skw_room_find_or_create_params_t params, skw_room_data_field_t data_fields)
	NameでRoomを検索し、存在しない場合は新規作成します。
skw_room_err_t	skw_room_join (const skw_room_join_params_t params, skw_room_member_data_field_t data_fields)
	指定したRoomにLocalPersonとしてJoinします。
skw_room_err_t	skw_room_update_metadata (const skw_room_update_metadata_params_t *params)
	RoomのMetadataを更新します。
skw_room_err_t	skw_room_register_handlers (const skw_room_handlers_t *handlers)
	Roomのイベント通知を受け取るハンドラを登録します。登録できる集合は単一で、再登録すると上書きされます。
skw_room_err_t	skw_room_unregister_handlers (void)
	登録済みのイベント通知ハンドラを解除します。

詳解

Roomの検索・作成・参加とイベントハンドラの登録。

マクロ定義詳解

◆ SKW_ROOM_CREATE_PARAMS_INIT

#define SKW_ROOM_CREATE_PARAMS_INIT ( ... )

値:

{__VA_ARGS__}

skw_room_create_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

◆ SKW_ROOM_FIND_BY_ID_PARAMS_INIT

#define SKW_ROOM_FIND_BY_ID_PARAMS_INIT ( ... )

値:

{__VA_ARGS__}

skw_room_find_by_id_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

◆ SKW_ROOM_FIND_BY_NAME_PARAMS_INIT

#define SKW_ROOM_FIND_BY_NAME_PARAMS_INIT ( ... )

値:

{__VA_ARGS__}

skw_room_find_by_name_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

◆ SKW_ROOM_FIND_OR_CREATE_PARAMS_INIT

#define SKW_ROOM_FIND_OR_CREATE_PARAMS_INIT ( ... )

値:

{__VA_ARGS__}

skw_room_find_or_create_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

◆ SKW_ROOM_JOIN_PARAMS_INIT

#define SKW_ROOM_JOIN_PARAMS_INIT ( ... )

値:

{__VA_ARGS__}

skw_room_join_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

◆ SKW_ROOM_UPDATE_METADATA_PARAMS_INIT

#define SKW_ROOM_UPDATE_METADATA_PARAMS_INIT ( ... )

値:

{__VA_ARGS__}

skw_room_update_metadata_params_tの初期化子。指定しなかったフィールドには既定値が入ります。

型定義詳解

◆ skw_room_on_member_joined_t

typedef void(* skw_room_on_member_joined_t) (const char *room_id, const char *member_id)

Memberが参加したときに呼ばれます。

引数

room_id	対象のRoomID
member_id	参加したMemberのID

◆ skw_room_on_member_left_t

typedef void(* skw_room_on_member_left_t) (const char *room_id, const char *member_id)

Memberが退出したときに呼ばれます。

引数

room_id	対象のRoomID
member_id	退出したMemberのID

◆ skw_room_on_member_metadata_updated_t

typedef void(* skw_room_on_member_metadata_updated_t) (const char *room_id, const char *member_id, const char *metadata)

MemberのMetadataが更新されたときに呼ばれます。

引数

room_id	対象のRoomID
member_id	対象のMemberのID
metadata	更新後のMetadata（イベントに含まれない場合はNULL）

◆ skw_room_on_publication_metadata_updated_t

typedef void(* skw_room_on_publication_metadata_updated_t) (const char *room_id, const char *publication_id, const char *metadata)

PublicationのMetadataが更新されたときに呼ばれます。

引数

room_id	対象のRoomID
publication_id	対象のPublicationのID
metadata	更新後のMetadata（イベントに含まれない場合はNULL）

◆ skw_room_on_publication_subscribed_t

typedef void(* skw_room_on_publication_subscribed_t) (const char *room_id, const char *subscription_id, const char *member_id)

PublicationがSubscribeされたときに呼ばれます。

引数

room_id	対象のRoomID
subscription_id	SubscriptionのID
member_id	SubscribeしたMemberのID

◆ skw_room_on_publication_unsubscribed_t

typedef void(* skw_room_on_publication_unsubscribed_t) (const char *room_id, const char *subscription_id, const char *member_id)

PublicationがUnsubscribeされたときに呼ばれます。

引数

room_id	対象のRoomID
subscription_id	SubscriptionのID
member_id	UnsubscribeしたMemberのID

◆ skw_room_on_room_closed_t

typedef void(* skw_room_on_room_closed_t) (const char *room_id)

Roomが削除されたときに呼ばれます。

引数

room_id 対象のRoomID

◆ skw_room_on_room_metadata_updated_t

typedef void(* skw_room_on_room_metadata_updated_t) (const char *room_id, const char *metadata)

RoomのMetadataが更新されたときに呼ばれます。

引数

room_id	対象のRoomID
metadata	更新後のMetadata（イベントに含まれない場合はNULL）

◆ skw_room_on_stream_published_t

typedef void(* skw_room_on_stream_published_t) (const char *room_id, const char *publication_id, const char *publisher_id, skw_room_publication_content_type_t content_type)

StreamがPublishされたときに呼ばれます。

引数

room_id	対象のRoomID
publication_id	PublicationのID
publisher_id	PublishしたMember（Publisher）のID
content_type	Publicationのコンテンツ種別

◆ skw_room_on_stream_unpublished_t

typedef void(* skw_room_on_stream_unpublished_t) (const char *room_id, const char *publication_id, const char *publisher_id)

StreamがUnpublishされたときに呼ばれます。

引数

room_id	対象のRoomID
publication_id	PublicationのID
publisher_id	UnpublishしたMember（Publisher）のID

列挙型詳解

◆ skw_room_err_t

enum skw_room_err_t

Room APIのエラーコード。

列挙値
SKW_ROOM_OK	正常終了
SKW_ROOM_ERR_NULL_ARGS	引数がNULL
SKW_ROOM_ERR_INVALID_ARGS	引数の値が不正
SKW_ROOM_ERR_CONTEXT_NOT_INITED	Contextが初期化されていない
SKW_ROOM_ERR_CONTEXT_NOT_SETUP	Contextがセットアップされていない
SKW_ROOM_ERR_REQUEST_FAILED	リクエストの実行に失敗
SKW_ROOM_ERR_MUTEX_UNLOCK_FAILED	Room APIのアンロックに失敗
SKW_ROOM_ERR_CALLED_IN_HANDLER	イベントハンドラ内から呼ばれた
SKW_ROOM_ERR_CAPACITY_EXHAUSTED	取得結果が格納上限を超えた（上限までは格納済み）
SKW_ROOM_ERR_SEND_FAILED	リクエストの送信に失敗
SKW_ROOM_ERR_TIMEOUT	応答の受信がタイムアウトした
SKW_ROOM_ERR_CONNECTION_CLOSED	応答待ちの間に接続が切断された
SKW_ROOM_ERR_RESPONSE_TOO_LARGE	応答が受信バッファのサイズを超過した
SKW_ROOM_ERR_RESPONSE_PARSE_FAILED	応答の解析に失敗した
SKW_ROOM_ERR_CONNECTION_FAILED	サーバーとの接続の確立に失敗
SKW_ROOM_ERR_ALREADY_JOINED	すでにLocalPersonが存在する（disposeで解放するまで再joinできない）
SKW_ROOM_ERR_UNKNOWN	不明なエラー
SKW_ROOM_ERR_BAD_REQUEST	リクエストパラメータが不正
SKW_ROOM_ERR_UNAUTHORIZED	AuthTokenが不正、もしくは有効期限切れ
SKW_ROOM_ERR_FORBIDDEN	必要な権限が無い
SKW_ROOM_ERR_NOT_FOUND	リソースが見つからない
SKW_ROOM_ERR_ALREADY_EXIST	すでに存在するリソースを作成しようとした
SKW_ROOM_ERR_TOO_LARGE	リクエストパラメータが大きすぎる
SKW_ROOM_ERR_TOO_MANY_REQUESTS	レートリミット超過
SKW_ROOM_ERR_SERVER_INTERNAL	サーバー内部エラー
SKW_ROOM_ERR_SERVER_BUSY	サーバーが過負荷で一時的に利用できない

関数詳解

◆ skw_room_create()

skw_room_err_t skw_room_create	(	const skw_room_create_params_t *	params,
		skw_room_data_field_t *	data_fields )

指定したパラメータでRoomを新規作成します。

引数

params	作成パラメータのポインタ
data_fields	作成したRoomの情報を格納する出力先のポインタ

戻り値: エラーコード

◆ skw_room_find_by_id()

skw_room_err_t skw_room_find_by_id	(	const skw_room_find_by_id_params_t *	params,
		skw_room_data_field_t *	data_fields )

IDでRoomを検索します。

引数

params	検索パラメータのポインタ
data_fields	取得したRoomの情報を格納する出力先のポインタ

戻り値: エラーコード

◆ skw_room_find_by_name()

skw_room_err_t skw_room_find_by_name	(	const skw_room_find_by_name_params_t *	params,
		skw_room_data_field_t *	data_fields )

NameでRoomを検索します。

引数

params	検索パラメータのポインタ
data_fields	取得したRoomの情報を格納する出力先のポインタ

戻り値: エラーコード

◆ skw_room_find_or_create()

skw_room_err_t skw_room_find_or_create	(	const skw_room_find_or_create_params_t *	params,
		skw_room_data_field_t *	data_fields )

NameでRoomを検索し、存在しない場合は新規作成します。

引数

params	検索/作成パラメータのポインタ
data_fields	取得または作成したRoomの情報を格納する出力先のポインタ

戻り値: エラーコード

◆ skw_room_join()

skw_room_err_t skw_room_join	(	const skw_room_join_params_t *	params,
		skw_room_member_data_field_t *	data_fields )

指定したRoomにLocalPersonとしてJoinします。

引数

params	Joinパラメータのポインタ
data_fields	JoinしたMemberの情報を格納する出力先のポインタ（不要ならNULL）。

戻り値: エラーコード

◆ skw_room_register_handlers()

skw_room_err_t skw_room_register_handlers ( const skw_room_handlers_t * handlers )

Roomのイベント通知を受け取るハンドラを登録します。登録できる集合は単一で、再登録すると上書きされます。

引数

handlers Roomのイベント通知を受け取るハンドラのポインタ

戻り値: エラーコード

◆ skw_room_unregister_handlers()

skw_room_err_t skw_room_unregister_handlers ( void )

登録済みのイベント通知ハンドラを解除します。

戻り値: エラーコード

◆ skw_room_update_metadata()

skw_room_err_t skw_room_update_metadata ( const skw_room_update_metadata_params_t * params )

RoomのMetadataを更新します。

引数

params 更新パラメータのポインタ

戻り値: エラーコード

データ構造

マクロ定義

型定義

列挙型

関数

詳解

マクロ定義詳解

◆ SKW_ROOM_CREATE_PARAMS_INIT

◆ SKW_ROOM_FIND_BY_ID_PARAMS_INIT

◆ SKW_ROOM_FIND_BY_NAME_PARAMS_INIT

◆ SKW_ROOM_FIND_OR_CREATE_PARAMS_INIT

◆ SKW_ROOM_JOIN_PARAMS_INIT

◆ SKW_ROOM_UPDATE_METADATA_PARAMS_INIT

型定義詳解

◆ skw_room_on_member_joined_t

◆ skw_room_on_member_left_t

◆ skw_room_on_member_metadata_updated_t

◆ skw_room_on_publication_metadata_updated_t

◆ skw_room_on_publication_subscribed_t

◆ skw_room_on_publication_unsubscribed_t

◆ skw_room_on_room_closed_t

◆ skw_room_on_room_metadata_updated_t

◆ skw_room_on_stream_published_t

◆ skw_room_on_stream_unpublished_t

列挙型詳解

◆ skw_room_err_t

関数詳解

◆ skw_room_create()

◆ skw_room_find_by_id()

◆ skw_room_find_by_name()

◆ skw_room_find_or_create()

◆ skw_room_join()

◆ skw_room_register_handlers()

◆ skw_room_unregister_handlers()

◆ skw_room_update_metadata()