wl_proxy(3)

📦
version 1.26.0 · 12 versions
, in arch rolling, fedora 43, fedora 44, nixpkgs unstable, ubuntu stonking

💖 NAME 💖

wl_proxy — bestie, this is the client-side representation of a protocol object ✨ like, the little local avatar of a thing that actually lives in the compositor 💅

🌸 SYNOPSIS 🌸

#include <wayland-client-core.h>

🎀 Public Member Functions 🎀

struct wl_proxy * wl_proxy_create (struct wl_proxy *factory, const struct wl_interface *interface)
void wl_proxy_destroy (struct wl_proxy *proxy)
int wl_proxy_add_listener (struct wl_proxy *proxy, void(**implementation)(void), void *data)
const void * wl_proxy_get_listener (struct wl_proxy *proxy)
int wl_proxy_add_dispatcher (struct wl_proxy *proxy, wl_dispatcher_func_t dispatcher, const void *implementation, void *data)
struct wl_proxy * wl_proxy_marshal_array_constructor (struct wl_proxy *proxy, uint32_t opcode, union wl_argument *args, const struct wl_interface *interface)
struct wl_proxy * wl_proxy_marshal_array_constructor_versioned (struct wl_proxy *proxy, uint32_t opcode, union wl_argument *args, const struct wl_interface *interface, uint32_t version)
struct wl_proxy * wl_proxy_marshal_flags (struct wl_proxy *proxy, uint32_t opcode, const struct wl_interface *interface, uint32_t version, uint32_t flags,...)
struct wl_proxy * wl_proxy_marshal_array_flags (struct wl_proxy *proxy, uint32_t opcode, const struct wl_interface *interface, uint32_t version, uint32_t flags, union wl_argument *args)
void wl_proxy_marshal (struct wl_proxy *proxy, uint32_t opcode,...)
struct wl_proxy * wl_proxy_marshal_constructor (struct wl_proxy *proxy, uint32_t opcode, const struct wl_interface *interface,...)
struct wl_proxy * wl_proxy_marshal_constructor_versioned (struct wl_proxy *proxy, uint32_t opcode, const struct wl_interface *interface, uint32_t version,...)
void wl_proxy_marshal_array (struct wl_proxy *proxy, uint32_t opcode, union wl_argument *args)
void wl_proxy_set_user_data (struct wl_proxy *proxy, void *user_data)
void * wl_proxy_get_user_data (struct wl_proxy *proxy)
uint32_t wl_proxy_get_version (struct wl_proxy *proxy)
uint32_t wl_proxy_get_id (struct wl_proxy *proxy)
void wl_proxy_set_tag (struct wl_proxy *proxy, const char *const *tag)
const char *const * wl_proxy_get_tag (struct wl_proxy *proxy)
const char * wl_proxy_get_class (struct wl_proxy *proxy)
const struct wl_interface * wl_proxy_get_interface (struct wl_proxy *proxy)
struct wl_display * wl_proxy_get_display (struct wl_proxy *proxy)
void wl_proxy_set_queue (struct wl_proxy *proxy, struct wl_event_queue *queue)
const char * wl_event_queue_get_name (const struct wl_event_queue *queue)
void * wl_proxy_create_wrapper (void *proxy)
void wl_proxy_wrapper_destroy (void *proxy_wrapper)

(ok so heads up, these are not member symbols, they're just hanging out nearby 🫶)

#define WL_MARSHAL_FLAG_DESTROY   (1 << 0)

✨ Detailed Description ✨

Represents a protocol object on the client side. Yes, again. It's that iconic 👑

So here's the tea, bestie: a wl_proxy is a client-side proxy standing in for an object that actually exists over in the compositor. This proxy has one job and it ate: it takes the requests clients make with wl_proxy_marshal() and converts them into Wayland's wire format 🔥. And the events coming back from the compositor? Also handled by the proxy, which then calls the handler you set with wl_proxy_add_listener() 💅.

⚠️ Note: apart from the function wl_proxy_set_queue(), functions that access a wl_proxy are not normally used by client code. Clients should normally use the higher level interface generated by the scanner to interact with compositor objects. Like, that's the whole vibe — you're not supposed to be down here in the weeds unless you know what you're doing 🙈

💜 Member Function Documentation 💜

💫 const char * wl_event_queue_get_name (const struct wl_event_queue * queue)

Get the name of an event queue ✨

Parameters

  • queue — The queue to query

Return the human readable name for the event queue 🎀

This may be NULL if no name has been set. So like, don't be shocked if it's giving nothing, it's allowed to 💀

💫 int wl_proxy_add_dispatcher (struct wl_proxy * proxy, wl_dispatcher_func_t dispatcher, const void * implementation, void * data)

Set a proxy's listener (with dispatcher) 🛠️

Parameters

  • proxy — The proxy object
  • dispatcher — The dispatcher to be used for this proxy
  • implementation — The dispatcher-specific listener implementation
  • data — User data to be associated with the proxy

Returns

0 on success or -1 on failure

Set proxy's listener to use dispatcher_func as its dispatcher and dispatcher_data as its dispatcher-specific implementation, and its user data to data. If a listener has already been set, this function fails and nothing is changed 🚫 (no partial glow-ups here, it's all or nothing).

The exact details of dispatcher_data depend on the dispatcher used. This function is intended to be used by language bindings, not user code. Language bindings bestie, that's the audience 👑

proxy must not be a proxy wrapper. Periodt.

💫 int wl_proxy_add_listener (struct wl_proxy * proxy, void(** implementation )(void), void * data)

Set a proxy's listener 🌸

Parameters

  • proxy — The proxy object
  • implementation — The listener to be added to proxy
  • data — User data to be associated with the proxy

Returns

0 on success or -1 on failure

Set proxy's listener to implementation and its user data to data. If a listener has already been set, this function fails and nothing is changed 🙅 (again: no takebacks, no merge, no "actually let me just tweak it").

implementation is a vector of function pointers. For an opcode n, implementation[n] should point to the handler of n for the given object. So like, index into it and that's your handler for that opcode, iykyk ✨

proxy must not be a proxy wrapper.

💫 struct wl_proxy * wl_proxy_create (struct wl_proxy * factory, const struct wl_interface * interface)

Create a proxy object with a given interface 🎀

Parameters

  • factory — Factory proxy object
  • interface — Interface the proxy object should use

Returns

A newly allocated proxy object or NULL on failure

This function creates a new proxy object with the supplied interface. The proxy object will have an id assigned from the client id space. The id should be created on the compositor side by sending an appropriate request with wl_proxy_marshal().

The proxy will inherit the display and event queue of the factory object. Genetics, but make it protocol 💅

⚠️ Note: This should not normally be used by non-generated code.

See also

wl_display, wl_event_queue, wl_proxy_marshal()

💫 void * wl_proxy_create_wrapper (void * proxy)

Create a proxy wrapper for making queue assignments thread-safe 🧵✨

Parameters

  • proxy — The proxy object to be wrapped

Returns

A proxy wrapper for the given proxy or NULL on failure

A proxy wrapper is type of 'struct wl_proxy' instance that can be used when sending requests instead of using the original proxy. A proxy wrapper does not have an implementation or dispatcher, and events received on the object is still emitted on the original proxy. Trying to set an implementation or dispatcher will have no effect but result in a warning being logged 📢 (the wrapper is like, "bestie I literally cannot do that").

Setting the proxy queue of the proxy wrapper will make new objects created using the proxy wrapper use the set proxy queue. Even though there is no implementation nor dispatcher, the proxy queue can be changed. This will affect the default queue of new objects created by requests sent via the proxy wrapper.

A proxy wrapper can only be destroyed using wl_proxy_wrapper_destroy(). No shortcuts 🔥

A proxy wrapper must be destroyed before the proxy it was created from.

If a user reads and dispatches events on more than one thread, it is necessary to use a proxy wrapper when sending requests on objects when the intention is that a newly created proxy is to use a proxy queue different from the proxy the request was sent on, as creating the new proxy and then setting the queue is not thread safe. Thread safety is the whole point, bestie, don't skip it 🫶

For example, a module that runs using its own proxy queue that needs to do display roundtrip must wrap the wl_display proxy object before sending the wl_display.sync request. For example:

struct wl_event_queue *queue = ...;
struct wl_display *wrapped_display;
struct wl_callback *callback;

wrapped_display = wl_proxy_create_wrapper(display);
wl_proxy_set_queue((struct wl_proxy *) wrapped_display, queue);
callback = wl_display_sync(wrapped_display);
wl_proxy_wrapper_destroy(wrapped_display);
wl_callback_add_listener(callback, ...);

💫 void wl_proxy_destroy (struct wl_proxy * proxy)

Destroy a proxy object 💀

Parameters

  • proxy — The proxy to be destroyed

proxy must not be a proxy wrapper.

🚨 Note: This function will abort in response to egregious errors, and will do so with the display lock held. This means SIGABRT handlers must not perform any actions that would attempt to take that lock, or a deadlock would occur. Like, genuinely, do not do that. Deadlock is not the vibe 😭

💫 const char * wl_proxy_get_class (struct wl_proxy * proxy)

Get the interface name (class) of a proxy object 🏷️

Parameters

  • proxy — The proxy object

Returns

The interface name of the object associated with the proxy

💫 struct wl_display * wl_proxy_get_display (struct wl_proxy * proxy)

Get the display of a proxy object 🖥️✨

Parameters

  • proxy — The proxy object

Returns

The wl_display the proxy is associated with

Since

1.23

💫 uint32_t wl_proxy_get_id (struct wl_proxy * proxy)

Get the id of a proxy object 🔢

Parameters

  • proxy — The proxy object

Returns

The id the object associated with the proxy

💫 const struct wl_interface * wl_proxy_get_interface (struct wl_proxy * proxy)

Get the interface of a proxy object 🎀

Parameters

  • proxy — The proxy object

Returns

The interface of the object associated with the proxy

Since

1.24

💫 const void * wl_proxy_get_listener (struct wl_proxy * proxy)

Get a proxy's listener 👀

Parameters

  • proxy — The proxy object

Returns

The address of the proxy's listener or NULL if no listener is set

Gets the address to the proxy's listener; which is the listener set with wl_proxy_add_listener.

This function is useful in clients with multiple listeners on the same interface to allow the identification of which code to execute. Like, "which one of you is running rn" energy 💅

If wl_proxy_add_dispatcher was used, this function returns the dispatcher_data pointer instead.

💫 const char *const * wl_proxy_get_tag (struct wl_proxy * proxy)

Get the tag of a proxy object 🏷️🦋

See wl_proxy_set_tag for details.

Parameters

  • proxy — The proxy object

Since

1.17.90

💫 void * wl_proxy_get_user_data (struct wl_proxy * proxy)

Get the user data associated with a proxy 📦

Parameters

  • proxy — The proxy object

Returns

The user data associated with proxy

💫 uint32_t wl_proxy_get_version (struct wl_proxy * proxy)

Get the protocol object version of a proxy object 🌈

Parameters

  • proxy — The proxy object

Returns

The protocol object version of the proxy or 0

Gets the protocol object version of a proxy object, or 0 if the proxy was created with unversioned API.

A returned value of 0 means that no version information is available, so the caller must make safe assumptions about the object's real version. Like, don't assume the best-case version, bestie — be safe about it 🙈

…and wl_display's version will always return 0. like, forever. it's the one thing in this whole library that never changes its mind. 💅

🦋 wl_proxy_marshal 🦋

void wl_proxy_marshal (struct wl_proxy * proxy, uint32_t opcode,  ...)

okay bestie, this is the "get a request ready to send to the compositor" girlie. 🚀

🌸 Parameters 🌸

  • proxy — the proxy object (the one doing the talking)
  • opcode — opcode of the request to be sent
  • ... — extra arguments for the given request

This function is similar to wl_proxy_marshal_constructor(), except it doesn't create proxies for new-id arguments. no new friends get born here, we're just passing messages. 🙈

💜 Note 💜

This should not normally be used by non-generated code. fr fr — if you're hand-writing this you're probably doing too much. 😭

🔍 See also 🔍

  • wl_proxy_create()

🧚 wl_proxy_marshal_array 🧚

void wl_proxy_marshal_array (struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args)

same energy as above, but you're handing over an array of arguments instead of a lil varargs situation. 💖

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • args — extra arguments for the given request

This function is similar to wl_proxy_marshal_array_constructor(), except it doesn't create proxies for new-id arguments. nope, no new-id proxies being summoned here. ✨

💜 Note 💜

This is intended to be used by language bindings and not in non-generated code. so if you're writing a binding for your fave language, hi, this is for you. 👑

🔍 See also 🔍

  • wl_proxy_marshal()

🌈 wl_proxy_marshal_array_constructor 🌈

struct wl_proxy * wl_proxy_marshal_array_constructor (struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args, const struct wl_interface * interface)

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • args — extra arguments for the given request
  • interface — the interface to use for the new proxy

This function translates a request given an opcode, an interface and a wl_argument array to the wire format and writes it to the connection buffer. it's giving "translator for the protocol gods". 🫶

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will inherit their version from their parent. nepotism but make it protocol. 💀

💜 Note 💜

This is intended to be used by language bindings and not in non-generated code.

🔍 See also 🔍

  • wl_proxy_marshal()

🍓 wl_proxy_marshal_array_constructor_versioned 🍓

struct wl_proxy * wl_proxy_marshal_array_constructor_versioned (struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args, const struct wl_interface * interface, uint32_t version)

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • args — extra arguments for the given request
  • interface — the interface to use for the new proxy
  • version — the protocol object version for the new proxy

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. This version takes an array of the union type wl_argument. yes bestie, this version takes the array. it's in the name. 💅

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified. you literally get to pick the version, main character behaviour. 👑

💜 Note 💜

This is intended to be used by language bindings and not in non-generated code.

🔍 See also 🔍

  • wl_proxy_marshal()

⭐ wl_proxy_marshal_array_flags ⭐

struct wl_proxy * wl_proxy_marshal_array_flags (struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, uint32_t version, uint32_t flags, union wl_argument * args)

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • interface — the interface to use for the new proxy
  • version — the protocol object version for the new proxy
  • flags — flags that modify marshalling behaviour
  • args — extra arguments for the given request

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. This version takes an array of the union type wl_argument. same girl, but now with flags. flags are the accessories of the protocol world. 🎀

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

The flag WL_MARSHAL_FLAG_DESTROY may be passed to ensure the proxy is destroyed atomically with the marshalling in order to prevent races that can occur if the display lock is dropped between the marshal and destroy operations. ⚠️ this one is lowkey important — it's the "do both things in one breath so nothing sneaks in between" flag. no cap.

💜 Note 💜

This is intended to be used by language bindings and not in non-generated code.

🔍 See also 🔍

  • wl_proxy_marshal_flags()

💖 wl_proxy_marshal_constructor 💖

struct wl_proxy * wl_proxy_marshal_constructor (struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface,  ...)

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • interface — the interface to use for the new proxy
  • ... — extra arguments for the given request

🌟 Returns 🌟

A new wl_proxy for the new_id argument or NULL on error. either you got a fresh proxy or you got nothing, that's the deal. 😭

This function translates a request given an opcode, an interface and extra arguments to the wire format and writes it to the connection buffer. The types of the extra arguments must correspond to the argument types of the method associated with the opcode in the interface. so like, match your types bestie, the wire format does NOT play. 💀

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will inherit their version from their parent. again with the inherited version, iconic family business. 🌸

💜 Note 💜

This should not normally be used by non-generated code.

🫶 wl_proxy_marshal_constructor_versioned 🫶

struct wl_proxy * wl_proxy_marshal_constructor_versioned (struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, uint32_t version,  ...)

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • interface — the interface to use for the new proxy
  • version — the protocol object version of the new proxy
  • ... — extra arguments for the given request

🌟 Returns 🌟

A new wl_proxy for the new_id argument or NULL on error.

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. short and sweet. ✨

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified. you said the version, you get the version. periodt. 💅

💜 Note 💜

This should not normally be used by non-generated code.

🔥 wl_proxy_marshal_flags 🔥

struct wl_proxy * wl_proxy_marshal_flags (struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, uint32_t version, uint32_t flags,  ...)

🌸 Parameters 🌸

  • proxy — the proxy object
  • opcode — opcode of the request to be sent
  • interface — the interface to use for the new proxy
  • version — the protocol object version of the new proxy
  • flags — flags that modify marshalling behaviour
  • ... — extra arguments for the given request

🌟 Returns 🌟

A new wl_proxy for the new_id argument or NULL on error.

Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer.

For new-id arguments, this function will allocate a new wl_proxy and send the ID to the server. The new wl_proxy will be returned on success or NULL on error with errno set accordingly. The newly created proxy will have the version specified.

The flag WL_MARSHAL_FLAG_DESTROY may be passed to ensure the proxy is destroyed atomically with the marshalling in order to prevent races that can occur if the display lock is dropped between the marshal and destroy operations. 🚨 yes, same warning as before, and yes it still matters. this is the atomic-girlboss move that keeps your multi-threaded self out of trouble. 👑

💜 Note 💜

This should not normally be used by non-generated code.

🎀 wl_proxy_set_queue 🎀

void wl_proxy_set_queue (struct wl_proxy * proxy, struct wl_event_queue * queue)

🌸 Parameters 🌸

  • proxy — the proxy object
  • queue — the event queue that will handle this proxy or NULL

Assign proxy to event queue. Events coming from proxy will be queued in queue from now. If queue is NULL, then the display's default queue is set to the proxy. so NULL = "go home to the default queue, girl". 🏠

In order to guarantee proper handing of all events which were queued before the queue change takes effect, it is required to dispatch the proxy's old event queue after setting a new event queue. ⚠️ do not skip this step, bestie, I'm begging. 😭

This is particularly important for multi-threaded setups, where it is possible for events to be queued to the proxy's old queue from a different thread during the invocation of this function. threads are out here doing their own thing at the worst possible moment, as always. 💀

To ensure that all events for a newly created proxy are dispatched on a particular queue, it is necessary to use a proxy wrapper if events are read and dispatched on more than one thread. See wl_proxy_create_wrapper() for more details. 👀

💜 Note 💜

By default, the queue set in proxy is the one inherited from parent.

🔍 See also 🔍

  • wl_display_dispatch_queue()

🦋 wl_proxy_set_tag 🦋

void wl_proxy_set_tag (struct wl_proxy * proxy, const char *const * tag)

A toolkit or application can set a unique tag on a proxy in order to identify whether an object is managed by itself or some external part. it's basically a name tag at a party but for your objects. 🏷️✨

To create a tag, the recommended way is to define a statically allocated constant char array containing some descriptive string. The tag will be the pointer to the non-const pointer to the beginning of the array. read that twice, it's a pointer-to-pointer situation and it will test you. 💅

For example, to define and set a tag on a surface managed by a certain subsystem:

static const char *my_tag = "my tag";

wl_proxy_set_tag((struct wl_proxy *) surface, &my_tag);

Then, in a callback with wl_surface as an argument, in order to check whether it's a surface managed by the same subsystem.

const char * const *tag;

tag = wl_proxy_get_tag((struct wl_proxy *) surface);
if (tag != &my_tag)
return;

 ...

For debugging purposes, a tag should be suitable to be included in a debug log entry, e.g.

const char * const *tag;

tag = wl_proxy_get_tag((struct wl_proxy *) surface);
printf("Got a surface with the tag %p (%s)\n",
       tag, (tag && *tag) ? *tag : "");

🌸 Parameters 🌸

  • proxy — the proxy object
  • tag — the tag

🌟 Since 🌟

1.17.90

🌸 wl_proxy_set_user_data 🌸

void wl_proxy_set_user_data (struct wl_proxy * proxy, void * user_data)

🌸 Parameters 🌸

  • proxy — the proxy object
  • user_data — the data to be associated with proxy

Set the user data associated with proxy. When events for this proxy are received, user_data will be supplied to its listener. it's like tucking a lil note into your proxy's pocket for later. 💌

💜 wl_proxy_wrapper_destroy 💜

void wl_proxy_wrapper_destroy (void * proxy_wrapper)

🌸 Parameters 🌸

  • proxy_wrapper — the proxy wrapper to be destroyed

Destroy a proxy wrapper. bye bestie, it was real. 👋✨

okay so this section is literally the entourage of wl_proxy — the little related symbols that ride shotgun 🫶. There's just one bestie here, but she's important, so let's give her main character energy:

  • #define WL_MARSHAL_FLAG_DESTROY — value: (1 << 0) — tagged [related]. No cap, this flag does exactly one thing and does it iconically: it destroys the proxy after marshalling 💅. That's it, that's the whole vibe. Marshalling happens, proxy says bye-bye. periodt.
fr fr, if you were hoping for a whole list of related symbols, bestie, this is the whole party — one #define and a dream 🌸

✍️ Author 🎀

Generated automatically by Doxygen for Wayland from the source code. 🦋

(not a human author, just a robot doing her little documentation slay 🤖✨)

okay that's the whole page bestie, we made it to the end of the trio of parts 🥳💖. This icon of a manual page is from Wayland, Version 1.26.0, and it lives in section 3 as wl_proxy(3) — so if you need her again, just holler and she'll show up. bye diva 👑💜🌸

📦 where this page comes from