Back

wayland-client-core.h

wl_display_connect指定名のディスプレイに接続
wl_display_connect_to_fdすでに開いている fd でディスプレイ接続
wl_display_disconnectディスプレイの接続を閉じる
wl_display_get_fdディスプレイに関連付けられた fd を取得
wl_display_dispatch受信イベントを処理
wl_display_dispatch_queue指定キューのイベントのディスパッチ
wl_display_dispatch_pendingイベントのディスパッチ (ブロックなし)
wl_display_dispatch_queue_pending指定キューのイベントのディスパッチ (ブロックなし)
wl_display_get_errorディスプレイ上で最後に発生したエラーを取得
wl_display_get_protocol_errorプロトコルエラーの情報を取得
wl_display_flushクライアントバッファ内の要求をサーバーに送る
wl_display_roundtripサーバーがすべての要求を処理するまで待つ
wl_display_roundtrip_queueサーバーがすべての要求を処理するまで待つ(キュー指定)
wl_display_create_queue新しいイベントキューを作成
wl_display_prepare_read_queueキューにイベントを読み込む準備をする
wl_display_prepare_readfd からイベントを読み込む準備をする
wl_display_cancel_readfd の読み込み意思を取り消す
wl_display_read_eventsfd からイベント読み込み 
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_dispatch(struct wl_display *display);
デフォルトのイベントキューに、イベントをディスパッチする。
キューが空の場合、イベントが発生するまで待つ。

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

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

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

ver 1.0.2 から
戻り値
ディスパッチされたイベントの数。失敗時は -1。
int wl_display_get_error(struct wl_display *display);
ディスプレイ上で最後に発生したエラー (サーバーまたはクライアント上で発生したもの) を返す。
この関数が 0 以外の値を返すと、ディスプレイは使用できなくなる。
戻り値
エラーコード。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。
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);
fd からイベントを読み込む準備をする。
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() を呼び出す。