Proxy (wayland.Wayland.Proxy)

Types

type ('a, +'v, 'role) t

An ('a, 'v, 'role) t is a proxy used by 'role to send messages to an object with interface 'a and version in 'v.

val user_data : ('a, _, 'role) t -> ('a, 'role) S.user_data

user_data t returns the data attached to the proxy when it was created.

This just calls the application's user_data method, if any. Returns No_data if nothing was attached.

val cast_version : ('a, _, 'role) t -> ('a, _, 'role) t

If the version rules turn out to be too restrictive, this can be used to disable them.

Using this incorrectly may lead to a protocol error (such as receiving an event for which no handler was registered).

Metadata

val version : (_, _, _) t -> int32

val metadata : ('a, _, 'role) t -> (module Metadata.S with type t = 'a)

val ty : ('a, _, 'role) t -> 'a Metadata.ty

val interface : (_, _, _) t -> string

Lifecycle

val delete : (_, _, [< `Client | `Server ]) t -> unit

delete t removes t from the object table. For servers, it also sends a delete event from object 1 if the object was client-allocated.

val on_delete : (_, _, _) t -> (unit -> unit) -> unit

on_delete t f calls f when t is deleted, either by delete being called (on the server) or when the client receives confirmation of the deletion from the server. f will also be called if the connection ends.

val can_send : (_, _, _) t -> bool

can_send t is true if the proxy can still be used in out-going messages. It becomes false after calling delete or shutdown_send.

val transport_up : (_, _, _) t -> bool

transport_up t is true if t's connection is still active. This is false after we read or send end-of-file on the connection.

Handlers

type ('a, 'v, 'role) proxy := ('a, 'v, 'role) t

Alias for use inside this file only

module Handler : sig ... end

Handlers for normal objects.

module Service_handler : sig ... end

Handlers for services (objects added via the registry).

Functions for use by generated code

You should not need to use these functions directly. Instead, run wayland-scanner-ocaml to generate typed wrappers and use the wrappers instead.

val id : (_, _, _) t -> int32

id t is t's object ID. Use this to refer to the object in a message.

raises Invalid_argument
if the proxy has been destroyed (can no longer be used for sending).

val id_opt : (_, _, _) t option -> int32

Like id but returns 0l for None.

val alloc : 
  ('a, _, _) t ->
  op:int ->
  ints:int ->
  strings:string option list ->
  arrays:string list ->
  ('a, [ `W ]) Msg.t

alloc t ~op ~ints ~strings ~arrays is a fresh message for t's op operation. The message is the right size for ints integer arguments, all the strings in strings, and all the arrays in arrays.

val send : ('a, _, [< `Client | `Server ]) t -> ('a, [ `W ]) Msg.t -> unit

send t msg enqueues msg on t's connection.

val spawn : 
  (_, 'v, [< `Client | `Server ] as 'role) t ->
  ['a, 'v, 'role] Handler.t ->
  ('a, 'v, 'role) t

Create a new proxy on t's connection with an unused ID. The new object has the same version as its parent.

val spawn_bind : 
  (_, _, [< `Client | `Server ] as 'role) t ->
  (['a, 'v, 'role] Service_handler.t * int32) ->
  ('a, 'v, 'role) t

Like spawn but the child's version is given explicitly, not inherited from the parent. This is used for binding with the global registry.

val shutdown_send : (_, _, _) t -> unit

shutdown_send t indicates that you will no longer call send on t. Call this after sending a destructor message. Attempts to send using the proxy after this will fail.

val shutdown_recv : (_, _, _) t -> unit

shutdown_recv t indicates that we will no longer receive messages addressed to t. Call this after receiving a destructor message.

val unknown_event : int -> string

A suitable string to display for an unknown event number.

val unknown_request : int -> string

A suitable string to display for an unknown request number.

Logging and tracing

module type TRACE = sig ... end

Pass a TRACE module when connecting to trace protocol messages.

val pp : (_, _, _) t Fmt.t

val pp_transport : (_, _, _) t Fmt.t

pp_transport calls S.transport#pp on the proxy's transport.