Server API¶
Server Introduction¶
The open-source reference implementation of Wayland protocol is split in two C libraries, Client API and libwayland-server. Their main responsibility is to handle the Inter-process communication (IPC) with each other, therefore guaranteeing the protocol objects marshaling and messages synchronization.
The server library is designed to work much like libwayland-client, although it is considerably complicated due to the server needing to support multiple versions of the protocol. It is best to learn libwayland-client first.
Each open socket to a client is represented by a wl_client
. The
equvalent of the wl_proxy
that libwayland-client uses to represent an
object is wl_resource
for client-created objects, and wl_global
for objects created by the server.
Often a server is also a client for another Wayland server, and thus must link
with both libwayland-client and libwayland-server. This produces some type
name conflicts (such as the client_wl_display
and
server_wl_display
, but the duplicate-but-not-the-same types are
opaque, and accessed only inside the correct library where it came from).
Naturally that means that the program writer needs to always know if a pointer
to a wl_display is for the server or client side and use the corresponding
functions.
-
WAYLAND_SERVER_H
¶ @file
Include the server API, deprecations and protocol C API.
warning: Use of this header file is discouraged. Prefer including wayland-server-core.h instead, which does not include the server protocol header and as such only defines the library API, excluding the deprecated API below.
-
wl_event_loop_fd_func_t
¶ File descriptor dispatch function type
Functions of this type are used as callbacks for file descriptor events.
Parameters: - fd – The file descriptor delivering the event.
- mask – Describes the kind of the event as a bitwise-or of:
- data – The user data argument of the related wl_event_loop_add_fd()
C: WL_EVENT_READABLE, @c WL_EVENT_WRITABLE, c WL_EVENT_HANGUP,
C: WL_EVENT_ERROR.
call.
Returns: If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.
Sa: wl_event_loop_add_fd() Memberof: wl_event_source
-
wl_event_loop_timer_func_t
¶ Timer dispatch function type
Functions of this type are used as callbacks for timer expiry.
Parameters: - data – The user data argument of the related wl_event_loop_add_timer()
call.
Returns: If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.
Sa: wl_event_loop_add_timer() Memberof: wl_event_source
-
wl_event_loop_signal_func_t
¶ Signal dispatch function type
Functions of this type are used as callbacks for (POSIX) signals.
Param: signal_number
Parameters: - data – The user data argument of the related wl_event_loop_add_signal()
call.
Returns: If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.
Sa: wl_event_loop_add_signal() Memberof: wl_event_source
-
wl_event_loop_idle_func_t
¶ Idle task function type
Functions of this type are used as callbacks before blocking in wl_event_loop_dispatch().
Parameters: - data – The user data argument of the related wl_event_loop_add_idle()
call.
Sa: wl_event_loop_add_idle() wl_event_loop_dispatch() Memberof: wl_event_source
struct: | wl_event_loop |
---|
An event loop context
Usually you create an event loop context, add sources to it, and call wl_event_loop_dispatch() in a loop to process events.
sa: | wl_event_source |
---|
-
struct wl_event_loop *
wl_event_loop_create
()¶ Struct: wl_event_source An abstract event source
This is the generic type for fd, timer, signal, and idle sources. Functions that operate on specific source types must not be used with a different type, even if the function signature allows it.
-
wl_display_global_filter_func_t
¶ A filter function for wl_global objects
Parameters: - client – The client object
- global – The global object to show or hide
- data – The user data pointer
A filter function enables the server to decide which globals to advertise to each client.
When a wl_global filter is set, the given callback funtion will be called during wl_global advertisment and binding.
This function should return true if the global object should be made visible to the client or false otherwise.
-
wl_client_for_each
(client, list)¶ Iterate over a list of clients.
-
struct
wl_listener
¶ Class: wl_listener A single listener for Wayland signals
wl_listener provides the means to listen for wl_signal notifications. Many Wayland objects use wl_listener for notification of significant events like object destruction.
Clients should create wl_listener objects manually and can register them as listeners to signals using #wl_signal_add, assuming the signal is directly accessible. For opaque structs like wl_event_loop, adding a listener should be done through provided accessor methods. A listener can only listen to one signal at a time.
struct wl_listener your_listener;
your_listener.notify = your_callback_method;
// Direct access wl_signal_add(&some_object->destroy_signal, &your_listener);
// Accessor access wl_event_loop *loop = …; wl_event_loop_add_destroy_listener(loop, &your_listener);
If the listener is part of a larger struct, #wl_container_of can be used to retrieve a pointer to it:
void your_listener(struct wl_listener *listener, void *data) {
struct your_data *data;
your_data = wl_container_of(listener, data, your_member_name);
}
If you need to remove a listener from a signal, use wl_list_remove().
wl_list_remove(&your_listener.link);
Sa: wl_signal
-
struct
wl_signal
¶ Class: wl_signal A source of a type of observable event
Signals are recognized points where significant events can be observed. Compositors as well as the server can provide signals. Observers are wl_listener’s that are added through #wl_signal_add. Signals are emitted using #wl_signal_emit, which will invoke all listeners until that listener is removed by wl_list_remove() (or whenever the signal is destroyed).
Sa: wl_listener for more information on using wl_signal
-
void
wl_signal_init
(struct wl_signal * signal)¶ Initialize a new @ref wl_signal for use.
Parameters: - signal – The signal that will be initialized
Memberof: wl_signal
-
void
wl_signal_add
(struct wl_signal * signal, struct wl_listener * listener)¶ Add the specified listener to this signal.
Parameters: - signal – The signal that will emit events to the listener
- listener – The listener to add
Memberof: wl_signal
-
struct wl_listener *
wl_signal_get
(struct wl_signal * signal, wl_notify_func_t notify)¶ Gets the listener struct for the specified callback.
Parameters: - signal – The signal that contains the specified listener
- notify – The listener that is the target of this search
Returns: the list item that corresponds to the specified listener, or NULL
if none was found
Memberof: wl_signal
-
void
wl_signal_emit
(struct wl_signal * signal, void * data)¶ Emits this signal, notifying all registered listeners.
Parameters: - signal – The signal object that will emit the signal
- data – The data that will be emitted with the signal
Memberof: wl_signal
-
struct
wl_socket
¶ some doc about wl_socket
-
struct
wl_client
¶ some doc about wl_client
-
void
wl_client_flush
(struct wl_client * client)¶ Flush pending events to the client
Parameters: - client – The client object
Events sent to clients are queued in a buffer and written to the socket later - typically when the compositor has handled all requests and goes back to block in the event loop. This function flushes all queued up events for a client immediately.
Memberof: wl_client
-
struct wl_display *
wl_client_get_display
(struct wl_client * client)¶ Get the display object for the given client
Parameters: - client – The client object
Returns: The display object the client is associated with.
Memberof: wl_client
-
struct wl_client *
wl_client_create
(struct wl_display * display, int fd)¶ Create a client for the given file descriptor
Parameters: - display – The display object
- fd – The file descriptor for the socket to the client
Returns: The new client object or NULL on failure.
Given a file descriptor corresponding to one end of a socket, this function will create a wl_client struct and add the new client to the compositors client list. At that point, the client is initialized and ready to run, as if the client had connected to the servers listening socket. When the client eventually sends requests to the compositor, the wl_client argument to the request handler will be the wl_client returned from this function.
The other end of the socket can be passed to wl_display_connect_to_fd() on the client side or used with the WAYLAND_SOCKET environment variable on the client side.
Listeners added with wl_display_add_client_created_listener() will be notified by this function after the client is fully constructed.
On failure this function sets errno accordingly and returns NULL.
Memberof: wl_display
-
void
wl_client_get_credentials
(struct wl_client * client, pid_t * pid, uid_t * uid, gid_t * gid)¶ Return Unix credentials for the client
Parameters: - client – The display object
- pid – Returns the process ID
- uid – Returns the user ID
- gid – Returns the group ID
This function returns the process ID, the user ID and the group ID for the given client. The credentials come from getsockopt() with SO_PEERCRED, on the client socket fd. All the pointers can be NULL, if the caller is not interested in a particular ID.
Be aware that for clients that a compositor forks and execs and then connects using socketpair(), this function will return the credentials for the compositor. The credentials for the socketpair are set at creation time in the compositor.
Memberof: wl_client
-
int
wl_client_get_fd
(struct wl_client * client)¶ Get the file descriptor for the client
Parameters: - client – The display object
Returns: The file descriptor to use for the connection
This function returns the file descriptor for the given client.
Be sure to use the file descriptor from the client for inspection only. If the caller does anything to the file descriptor that changes its state, it will likely cause problems.
See also wl_client_get_credentials(). It is recommended that you evaluate whether wl_client_get_credentials() can be applied to your use case instead of this function.
If you would like to distinguish just between the client and the compositor itself from the client’s request, it can be done by getting the client credentials and by checking the PID of the client and the compositor’s PID. Regarding the case in which the socketpair() is being used, you need to be careful. Please note the documentation for wl_client_get_credentials().
This function can be used for a compositor to validate a request from a client if there are additional information provided from the client’s file descriptor. For instance, suppose you can get the security contexts from the client’s file descriptor. The compositor can validate the client’s request with the contexts and make a decision whether it permits or deny it.
Memberof: wl_client
-
struct wl_resource *
wl_client_get_object
(struct wl_client * client, uint32_t id)¶ Look up an object in the client name space
Parameters: - client – The client object
- id – The object id
Returns: The object or NULL if there is not object for the given ID
This looks up an object in the client object name space by its object ID.
Memberof: wl_client
-
void
wl_client_post_implementation_error
(struct wl_client * client, const char * msg, ...)¶ Report an internal server error
Parameters: - client – The client object
- msg – A printf-style format string
- ... – Format string arguments
Report an unspecified internal implementation error and disconnect the client.
Memberof: wl_client
-
_Bool
resource_is_deprecated
(struct wl_resource * resource)¶ Detect if a wl_resource uses the deprecated public definition.
Before Wayland 1.2.0, the definition of struct wl_resource was public. It was made opaque just before 1.2.0, and later new fields were added. The new fields cannot be accessed if a program is using the deprecated defition, as there would not be memory allocated for them.
The creation pattern for the deprecated definition was wl_resource_init() followed by wl_client_add_resource(). wl_resource_init() was an inline function and no longer exists, but binaries might still carry it. wl_client_add_resource() still exists for ABI compatiblity.
-
const char *
wl_resource_get_class
(struct wl_resource * resource)¶ Retrieve the interface name (class) of a resource object.
Parameters: - resource – The resource object
Memberof: wl_resource
-
struct wl_display *
wl_display_create
()¶ Create Wayland display object.
Returns: The Wayland display object. Null if failed to create This creates the wl_display object.
Memberof: wl_display
-
void
wl_display_destroy
(struct wl_display * display)¶ Destroy Wayland display object.
Parameters: - display – The Wayland display object which should be destroyed.
Returns: None.
This function emits the wl_display destroy signal, releases all the sockets added to this display, free’s all the globals associated with this display, free’s memory of additional shared memory formats and destroy the display object.
Sa: wl_display_add_destroy_listener Memberof: wl_display
-
void
wl_display_set_global_filter
(struct wl_display * display, wl_display_global_filter_func_t filter, void * data)¶ Set a filter function for global objects
Parameters: - display – The Wayland display object.
- filter – The global filter funtion.
- data – User data to be associated with the global filter.
Returns: None.
Set a filter for the wl_display to advertise or hide global objects to clients. The set filter will be used during wl_global advertisment to determine whether a global object should be advertised to a given client, and during wl_global binding to determine whether a given client should be allowed to bind to a global.
Clients that try to bind to a global that was filtered out will have an error raised.
Setting the filter NULL will result in all globals being advertised to all clients. The default is no filter.
Memberof: wl_display
-
uint32_t
wl_display_get_serial
(struct wl_display * display)¶ Get the current serial number
Parameters: - display – The display object
This function returns the most recent serial number, but does not increment it.
Memberof: wl_display
-
uint32_t
wl_display_next_serial
(struct wl_display * display)¶ Get the next serial number
Parameters: - display – The display object
This function increments the display serial number and returns the new value.
Memberof: wl_display
-
void
wl_display_destroy_clients
(struct wl_display * display)¶ Destroy all clients connected to the display
Parameters: - display – The display object
This function should be called right before wl_display_destroy() to ensure all client resources are closed properly. Destroying a client from within wl_display_destroy_clients() is safe, but creating one will leak resources and raise a warning.
Memberof: wl_display
-
int
wl_display_add_socket_fd
(struct wl_display * display, int sock_fd)¶ Add a socket with an existing fd to Wayland display for the clients to connect.
Parameters: - display – Wayland display to which the socket should be added.
- sock_fd – The existing socket file descriptor to be used
Returns: 0 if success. -1 if failed.
The existing socket fd must already be created, opened, and locked. The fd must be properly set to CLOEXEC and bound to a socket file with both bind() and listen() already called.
Memberof: wl_display
-
int
wl_display_add_socket
(struct wl_display * display, const char * name)¶ Add a socket to Wayland display for the clients to connect.
Parameters: - display – Wayland display to which the socket should be added.
- name – Name of the Unix socket.
Returns: 0 if success. -1 if failed.
This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display.
If NULL is passed as name, then it would look for WAYLAND_DISPLAY env variable for the socket name. If WAYLAND_DISPLAY is not set, then default wayland-0 is used.
The Unix socket will be created in the directory pointed to by environment variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not set, then this function fails and returns -1.
The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the socket name, must not exceed the maximum length of a Unix socket path. The function also fails if the user do not have write permission in the XDG_RUNTIME_DIR path or if the socket name is already in use.
Memberof: wl_display
-
void
wl_display_add_client_created_listener
(struct wl_display * display, struct wl_listener * listener)¶ - Registers a listener for the client connection signal.
When a new client object is created, @a listener will be notified, carrying a pointer to the new wl_client object.
ref: wl_client_create ref: wl_display ref: wl_listener
Parameters: - display – The display object
- listener – Signal handler object
-
struct wl_resource *
wl_resource_create
(struct wl_client * client, const struct wl_interface * interface, int version, uint32_t id)¶ Create a new resource object
Parameters: - client – The client owner of the new resource.
- interface – The interface of the new resource.
- version – The version of the new resource.
- id – The id of the new resource. If 0, an available id will be used.
Listeners added with @a wl_client_add_resource_created_listener will be notified at the end of this function.
Memberof: wl_resource
-
struct wl_protocol_logger *
wl_display_add_protocol_logger
(struct wl_display * display, wl_protocol_logger_func_t func, void * user_data)¶ Adds a new protocol logger.
When a new protocol message arrives or is sent from the server all the protocol logger functions will be called, carrying the
A: user_data pointer, the type of the message (request or event) and the actual message. The lifetime of the messages passed to the logger function ends when they return so the messages cannot be stored and accessed later.
A: errno is set on error.
Parameters: - display – The display object
- func – The function to call to log a new protocol message
- user_data – The user data pointer to pass to @a func
Returns: The protol logger object on success, NULL on failure.
Sa: wl_protocol_logger_destroy
Memberof: wl_display
-
void
wl_protocol_logger_destroy
(struct wl_protocol_logger * logger)¶ Destroys a protocol logger.
This function destroys a protocol logger and removes it from the display it was added to with @a wl_display_add_protocol_logger. The @a logger object becomes invalid after calling this function.
Sa: wl_display_add_protocol_logger Memberof: wl_protocol_logger
-
uint32_t *
wl_display_add_shm_format
(struct wl_display * display, uint32_t format)¶ Add support for a wl_shm pixel format
Parameters: - display – The display object
- format – The wl_shm pixel format to advertise
Returns: A pointer to the wl_shm format that was added to the list
or NULL if adding it to the list failed.
Add the specified wl_shm format to the list of formats the wl_shm object advertises when a client binds to it. Adding a format to the list means that clients will know that the compositor supports this format and may use it for creating wl_shm buffers. The compositor must be able to handle the pixel format when a client requests it.
The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.
Memberof: wl_display
-
struct wl_array *
wl_display_get_additional_shm_formats
(struct wl_display * display)¶ Get list of additional wl_shm pixel formats
Parameters: - display – The display object
This function returns the list of addition wl_shm pixel formats that the compositor supports. WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888 are always supported and not included in the array, but all formats added through wl_display_add_shm_format() will be in the array.
Sa: wl_display_add_shm_format() @private
Memberof: wl_display
-
struct wl_list *
wl_display_get_client_list
(struct wl_display * display)¶ Get the list of currently connected clients
Parameters: - display – The display object
This function returns a pointer to the list of clients currently connected to the display. You can iterate on the list by using the @a wl_client_for_each macro. The returned value is valid for the lifetime of the @a display. You must not modify the returned list, but only access it.
Sa: wl_client_for_each() Sa: wl_client_get_link() Sa: wl_client_from_link() Memberof: wl_display
-
struct wl_list *
wl_client_get_link
(struct wl_client * client)¶ Get the link by which a client is inserted in the client list
Parameters: - client – The client object
Sa: wl_client_for_each()
Sa: wl_display_get_client_list()
Sa: wl_client_from_link()
Memberof: wl_client
-
struct wl_client *
wl_client_from_link
(struct wl_list * link)¶ Get a wl_client by its link
Parameters: - link – The link of a wl_client
Sa: wl_client_for_each()
Sa: wl_display_get_client_list()
Sa: wl_client_get_link()
Memberof: wl_client
-
void
wl_client_add_resource_created_listener
(struct wl_client * client, struct wl_listener * listener)¶ Add a listener for the client’s resource creation signal
Parameters: - client – The client object
- listener – The listener to be added
When a new resource is created for this client the listener will be notified, carrying the new resource as the data argument.
Memberof: wl_client
-
void
wl_client_for_each_resource
(struct wl_client * client, wl_client_for_each_resource_iterator_func_t iterator, void * user_data)¶ Iterate over all the resources of a client
Parameters: - client – The client object
- iterator – The iterator function
- user_data – The user data pointer
The function pointed by @a iterator will be called for each resource owned by the client. The @a user_data will be passed as the second argument of the iterator function. If the @a iterator function returns @a WL_ITERATOR_CONTINUE the iteration will continue, if it returns @a WL_ITERATOR_STOP it will stop.
Creating and destroying resources while iterating is safe, but new resources may or may not be picked up by the iterator.
Sa: wl_iterator_result Memberof: wl_client
cond: | INTERNAL |
---|
-
void
wl_priv_signal_init
(struct wl_priv_signal * signal)¶ Initialize a wl_priv_signal object
wl_priv_signal is a safer implementation of a signal type, with the same API as wl_signal, but kept as a private utility of libwayland-server. It is safer because listeners can be removed from within wl_priv_signal_emit() without corrupting the signal’s list.
Before passing a wl_priv_signal object to any other function it must be initialized by useing wl_priv_signal_init().
Memberof: wl_priv_signal
-
void
wl_priv_signal_add
(struct wl_priv_signal * signal, struct wl_listener * listener)¶ Add a listener to a signal
The new listener will be called when calling wl_signal_emit(). If a listener is added to the signal while wl_signal_emit() is running it will be called from the next time wl_priv_signal_emit() is called. To remove a listener call wl_list_remove() on its link member.
Memberof: wl_priv_signal
-
struct wl_listener *
wl_priv_signal_get
(struct wl_priv_signal * signal, wl_notify_func_t notify)¶ Get a listener added to a signal
Returns the listener added to the given @a signal and with the given
A: notify function, or NULL if there isn’t any. Calling this function from withing wl_priv_signal_emit() is safe and will return the correct value.
Memberof: wl_priv_signal
-
void
wl_priv_signal_emit
(struct wl_priv_signal * signal, void * data)¶ Emit the signal, calling all the installed listeners
Iterate over all the listeners added to this @a signal and call their @a notify function pointer, passing on the given @a data. Removing or adding a listener from within wl_priv_signal_emit() is safe.
-
void
wl_priv_signal_final_emit
(struct wl_priv_signal * signal, void * data)¶ Emit the signal for the last time, calling all the installed listeners
Iterate over all the listeners added to this @a signal and call their @a notify function pointer, passing on the given @a data. Removing or adding a listener from within wl_priv_signal_emit() is safe, as is freeing the structure containing the listener.
A large body of external code assumes it’s ok to free a destruction listener without removing that listener from the list. Mixing code that acts like this and code that doesn’t will result in list corruption.
We resolve this by removing each item from the list and isolating it in another list. We discard it completely after firing the notifier. This should allow interoperability between code that unlinks its destruction listeners and code that just frees structures they’re in.
endcond: | INTERNAL |
---|
@cond
@endcond