Provided by: libwayland-doc_1.22.0-2.1build1_all bug

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)
       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)
       void wl_proxy_set_queue (struct wl_proxy *proxy, struct wl_event_queue *queue)
       void * wl_proxy_create_wrapper (void *proxy)
       void wl_proxy_wrapper_destroy (void *proxy_wrapper)

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.

       proxy must not be a proxy wrapper.

   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.

       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.

       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.

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

       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.

       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.

   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.

   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.

       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 error 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 error 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_array_flags (struct wl_proxy * proxy, uint32_t opcode,
       const struct wl_interface * interface, uint32_t version, uint32_t flags, 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
           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.

       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.

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

       See also
           wl_proxy_marshal_flags()

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

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

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

       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.

       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.

       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.

       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()

   void wl_proxy_set_tag (struct wl_proxy * proxy, const char *const * tag)
       Set the tag of a proxy object

       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.

       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.

       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

   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.

   void wl_proxy_wrapper_destroy (void * proxy_wrapper)
       Destroy a proxy wrapper

       Parameters
           proxy_wrapper The proxy wrapper to be destroyed

Author

       Generated automatically by Doxygen for Wayland from the source code.