Back

wayland-client-core.h

ディスプレイ
wl_display_connectWayland ディスプレイに接続
wl_display_connect_to_fdfd からディスプレイ接続
wl_display_disconnectディスプレイの接続を閉じる
wl_display_get_fdディスプレイに関連付けられた fd を取得
エラー
wl_display_get_errorディスプレイ上で最後に発生したエラーを取得
wl_display_get_protocol_errorプロトコルエラーの情報を取得
リクエスト
wl_display_flushクライアントバッファ内のリクエストをサーバーに送る
wl_display_roundtripサーバーがすべてのリクエストを処理するまで待つ
wl_display_roundtrip_queueサーバーがすべてのリクエストを処理するまで待つ (キュー指定)
イベント
wl_display_dispatchイベントのディスパッチ
wl_display_dispatch_pendingイベントのディスパッチ (ブロックなし)
wl_display_dispatch_queueイベントのディスパッチ (キュー指定)
wl_display_dispatch_queue_pendingイベントのディスパッチ (キュー指定、ブロックなし)
wl_display_create_queue新しいイベントキューを作成
wl_display_prepare_read_queueイベントを読み込む準備をする
wl_display_prepare_readイベントを読み込む準備をする (デフォルトキュー)
wl_display_cancel_readイベントの読み込み準備を取り消す
wl_display_read_eventsイベント読み込み
ディスプレイ
struct wl_display *wl_display_connect(const char *name);
Wayland ディスプレイに接続
name
ディスプレイの名前。
NULL の場合は、環境変数 WAYLAND_DISPLAY の名前が使われる。
環境変数が設定されていない場合は、"wayland-0"。
戻り値
NULL で失敗。
struct wl_display *wl_display_connect_to_fd(int fd);
すでに開いているファイルディスクリプタに Wayland ディスプレイを接続。

成功した場合は、fd の所有権を取得し、ディスプレイが破棄された時は、自動的に fd が閉じられる。
この関数が失敗した場合、fd は閉じられる。
戻り値
NULL で失敗。
void wl_display_disconnect(struct wl_display *display);
Wayland ディスプレイの接続を閉じて、全てのリソースを解放する。
int wl_display_get_fd(struct wl_display *display);
ディスプレイに関連付けられたファイルディスクリプタを取得する。
エラー
int wl_display_get_error(struct wl_display *display);
ディスプレイ上で最後に発生したエラー (サーバーまたはクライアント上で発生したもの) を返す。
戻り値
エラーコード。0 でエラーなし。
uint32_t wl_display_get_protocol_error(struct wl_display *display,
    const struct wl_interface **interface, uint32_t *id);
プロトコルエラーの情報を取得する。

int err = wl_display_get_error(display);

if (err == EPROTO) {
    code = wl_display_get_protocol_error(display, &interface, &id);
    handle_error(code, interface, id);
}
interface
NULL 以外で、エラーのあったインターフェイスのポインタを取得。
id
NULL 以外で、オブジェクト ID を取得。
オブジェクト ID が不明の場合は、0 を返す。
この関数の実行時点で、そのオブジェクトが存在しているという保証はない。
戻り値
エラーコード
リクエスト
int wl_display_flush(struct wl_display *display);
クライアントのバッファ内にある、すべてのリクエストデータを、サーバーに送信する。
クライアントがイベントを読み込む前に、常にこの関数を呼び出すべき。

一回でできるだけ多くのデータを書き込もうとするが、すべてのデータを書き込めなかった場合は -1 が返り、errno は EAGAIN になる。
戻り値
サーバーに送信されたバイト数。失敗時は -1。
int wl_display_roundtrip(struct wl_display *display);
サーバーが、現在発行されているすべてのリクエストの処理を完了するまで、ブロックする。
デフォルトのキューが対象となる。

この関数は、wl_display_dispatch_queue() を内部で使用する。
スレッドがイベントを読み込む準備をしている間は、この関数を呼び出すことはできない。それを行うと、デッドロックが発生する。
戻り値
成功した場合、ディスパッチされたイベントの数。失敗時は -1。
int wl_display_roundtrip_queue(struct wl_display *display, struct wl_event_queue *queue);
wl_display_roundtrip() のキュー指定版。
※指定キュー以外のイベントもディスパッチされる場合がある。
戻り値
成功した場合、ディスパッチされたイベントの数。失敗時は -1。
イベント
int wl_display_dispatch(struct wl_display *display);
デフォルトのイベントキューで、イベントをディスパッチする。
(サーバーから送られてきたイベントを、クライアント側で処理できるように、コールバック関数などを実行する)。
キューが空の場合は、イベントが発生するまで待つ。

マルチスレッドでは、この関数を呼び出す前に、poll() などの関数を手動で使わないこと。デッドロックが発生する可能性がある。

この関数は、正しいスレッドにディスパッチする限り、スレッドセーフである。
また、wl_display_prepare_read_queue() と互換性があり、同等の機能を内部で使用する。
prepare_read で準備している間は、この関数を呼び出すことはできない (使うと、デッドロックが発生する)。

※キューにイベントがあるかどうかを確認することはできない。
戻り値
ディスパッチされたイベントの数。
失敗時は -1 となり、errno が設定される。
int wl_display_dispatch_pending(struct wl_display *display);
wl_display_dispatch() と同等だが、キューが空の場合は、ブロックせずに 0 を返す。
戻り値
ディスパッチされたイベントの数。失敗時は -1。
int wl_display_dispatch_queue(struct wl_display *display, struct wl_event_queue *queue);
wl_display_dispatch() のキュー指定版。

※Wayland 1.5 以降、ディスプレイには、独自のイベント (delete_id 用) の余分なキューがあり、このキューは常にディスパッチされる。
そのため、指定キューがディスパッチされていなくても、0 以外の値を返す場合がある。
戻り値
ディスパッチされたイベントの数。
失敗時は -1。errno が設定される。
int wl_display_dispatch_queue_pending(struct wl_display *display, struct wl_event_queue *queue);
wl_display_dispatch_queue() と同等だが、キューが空の場合は、ブロックせずにすぐ戻る。
ver 1.0.2
戻り値
ディスパッチされたイベントの数。失敗時は -1。
struct wl_event_queue *wl_display_create_queue(struct wl_display *display);
新しいイベントキューを作成する。
戻り値
作成されたキュー。NULL で失敗。
int wl_display_prepare_read_queue(struct wl_display *display, struct wl_event_queue *queue);
wl_display_read_events() でイベントを読み込む前に、この関数を呼び出す必要がある。

実行すると、呼び出し元のスレッドで、イベントを読み込むという意思が通知される。
スレッドの読み込み準備が完了した後、wl_display_read_events() が呼び出されるまでの間、他のスレッドは fd から読み込むことができない。
この関数は、キューが空の場合、失敗する。

この関数を使った後は、wl_display_read_events() でイベントを読み込むか、wl_display_cancel_read() で読み込みをキャンセルする必要がある。

▼ 使用例 
while(wl_display_prepare_read_queue(display, queue) != 0)
    wl_display_dispatch_queue_pending(display, queue);

wl_display_flush(display);

ret = poll(fds, nfds, -1);
if(has_error(ret))
    wl_display_cancel_read(display);
else
    wl_display_read_events(display);

wl_display_dispatch_queue_pending(display, queue);
戻り値
0 で成功、-1 でイベントキューは空でない
int wl_display_prepare_read(struct wl_display *display);
wl_display_prepare_read_queue() と同等だが、デフォルトキューを使う。
void wl_display_cancel_read(struct wl_display *display);
wl_display_prepare_read() によって、イベントの読み込み準備を行った後に、イベントを読み込まず、操作をキャンセルする。
int wl_display_read_events(struct wl_display *display);
wl_display_prepare_read() の実行後、この関数でイベントを読み込む。

スレッドが読み込み準備をキャンセルした時、読み込み準備が整っている他のすべてのスレッドが、wl_display_cancel_read() または wl_display_read_events() を呼び出した場合、すべてのスレッドは、データを読み込まずに戻る。

キューに入っているイベントをディスパッチするには、wl_display_dispatch_pending() を呼び出す。