wl_proxy(3)

NAME
wl_proxy - Represents a protocol object on the client side.

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)
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)
const char * wl_proxy_get_class (struct wl_proxy *proxy)
void wl_proxy_set_queue (struct wl_proxy *proxy, struct wl_event_queue *queue)

Detailed Description

Represents a protocol object on the client side. A wl_proxy acts as a client side proxy to an object existing in the compositor. The proxy is responsible for converting requests made by the clients with wl_proxy_marshal() into Wayland's wire format. Events coming from the compositor are also handled by the proxy, which will in turn call the handler set with wl_proxy_add_listener().

Note:
    With the exception of function wl_proxy_set_queue(), functions accessing 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.

Member Function Documentation

  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.

The exact details of dispatcher_data depend on the dispatcher used. This function is intended to be used by language bindings, not user code.

  int wl_proxy_add_listener (struct wl_proxy * proxy, void(**)(void) implementation, 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.

implementation is a vector of function pointers. For an opcode n, implementation[n] should point to the handler of n for the given object.

  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.

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

See also:
    wl_display, wl_event_queue, wl_proxy_marshal()

  void wl_proxy_destroy (struct wl_proxy * proxy)
Destroy a proxy object

Parameters:
    proxy The proxy to be destroyed

  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

  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 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.

  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.

wl_display's version will always return 0.

  void wl_proxy_marshal (struct wl_proxy * proxy, uint32_t opcode, ...)
Prepare a request to be sent to the compositor

Parameters:
    proxy The proxy object
    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.

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

See also:
    wl_proxy_create()

  void wl_proxy_marshal_array (struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args)
Prepare a request to be sent to the compositor

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.

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

See also:
    wl_proxy_marshal()

  struct wl_proxy * wl_proxy_marshal_array_constructor (struct wl_proxy * proxy, uint32_t opcode, union wl_argument * args, const struct wl_interface * interface)
Prepare a request to be sent to the compositor

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.

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 errror with errno set accordingly. The newly created proxy will inherit their version from their parent.

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

See also:
    wl_proxy_marshal()

  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)
Prepare a request to be sent to the compositor

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.

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 errror with errno set accordingly. The newly created proxy will have the version specified.

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

See also:
    wl_proxy_marshal()

  struct wl_proxy * wl_proxy_marshal_constructor (struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, ...)
Prepare a request to be sent to the compositor

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

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.

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 errror with errno set accordingly. The newly created proxy will inherit their version from their parent.

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

  struct wl_proxy * wl_proxy_marshal_constructor_versioned (struct wl_proxy * proxy, uint32_t opcode, const struct wl_interface * interface, uint32_t version, ...)
Prepare a request to be sent to the compositor

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.

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 errror with errno set accordingly. The newly created proxy will have the version specified.

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

  void wl_proxy_set_queue (struct wl_proxy * proxy, struct wl_event_queue * queue)
Assign a proxy to an event 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.

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

See also:
    wl_display_dispatch_queue()

  void wl_proxy_set_user_data (struct wl_proxy * proxy, void * user_data)
Set the user data associated with a proxy

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.

Author

Generated automatically by Doxygen for Wayland from the source code.