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.
-
union
wl_argument
- #include <wayland-util.h>
Protocol message argument data types.
This union represents all of the argument types in the Wayland protocol wire format. The protocol implementation uses wl_argument within its marshalling machinery for dispatching messages between a client and a compositor.
- See
- wl_message
- See
- wl_interface
- See
- Wire Format
Public Members
-
int32_t
i
int
-
uint32_t
u
uint
-
wl_fixed_t
f
fixed
-
const char *
s
string
-
struct wl_object *
o
object
-
uint32_t
n
new_id
-
struct wl_array *
a
array
-
int32_t
h
fd
-
class
wl_array
- #include <wayland-util.h>
Dynamic array.
A wl_array is a dynamic array that can only grow until released. It is intended for relatively small allocations whose size is variable or not known in advance. While construction of a wl_array does not require all elements to be of the same size, wl_array_for_each() does require all elements to have the same type and size.
Public Functions
-
void
wl_array_init
(struct wl_array *array) Initializes the array.
- Parameters
array
: Array to initialize
-
void
wl_array_release
(struct wl_array *array) Releases the array data.
- Note
- Leaves the array in an invalid state.
- Parameters
array
: Array whose data is to be released
-
void *
wl_array_add
(struct wl_array *array, size_t size) Increases the size of the array by
size
bytes.- Return
- A pointer to the beginning of the newly appended space, or NULL when resizing fails.
- Parameters
array
: Array whose size is to be increasedsize
: Number of bytes to increase the size of the array by
Public Members
-
size_t
size
Array size.
-
size_t
alloc
Allocated space.
-
void *
data
Array data.
Related
-
wl_array_for_each
(pos, array)¶ Iterates over an array.
This macro expresses a for-each iterator for wl_array. It assigns each element in the array to
pos
, which can then be referenced in a trailing code block.pos
must be a pointer to the array element type, and all array elements must be of the same type and size.- See
- wl_list_for_each()
- Parameters
pos
: Cursor that each array element will be assigned toarray
: Array to iterate over
-
void
-
struct
wl_client
¶ Public Functions
-
void
wl_client_flush
(struct wl_client *client)¶ Flush pending events to the client.
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.
- Parameters
client
: The client object
-
struct wl_display *
wl_client_get_display
(struct wl_client *client)¶ Get the display object for the given client.
- Return
- The display object the client is associated with.
- Parameters
client
: The client object
-
void
wl_client_get_credentials
(struct wl_client *client, pid_t *pid, uid_t *uid, gid_t *gid)¶ Return Unix credentials for the client.
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.
- Parameters
client
: The display objectpid
: Returns the process IDuid
: Returns the user IDgid
: Returns the group 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.
-
int
wl_client_get_fd
(struct wl_client *client)¶ Get the file descriptor for the client.
This function returns the file descriptor for the given client.
- Return
- The file descriptor to use for the connection
- Parameters
client
: The display object
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.
-
struct wl_resource *
wl_client_get_object
(struct wl_client *client, uint32_t id)¶ Look up an object in the client name space.
This looks up an object in the client object name space by its object ID.
- Return
- The object or NULL if there is not object for the given ID
- Parameters
client
: The client objectid
: The object id
-
void
wl_client_post_implementation_error
(struct wl_client *client, char const *msg, ...)¶ Report an internal server error.
Report an unspecified internal implementation error and disconnect the client.
- Parameters
client
: The client objectmsg
: A printf-style format string...
: Format string arguments
-
struct wl_list *
wl_client_get_link
(struct wl_client *client)¶ Get the link by which a client is inserted in the client list.
- See
- wl_client_for_each()
- See
- wl_display_get_client_list()
- See
- wl_client_from_link()
- Parameters
client
: The client object
-
struct wl_client *
wl_client_from_link
(struct wl_list *link)¶ Get a wl_client by its link.
- See
- wl_client_for_each()
- See
- wl_display_get_client_list()
- See
- wl_client_get_link()
- Parameters
link
: The link of a 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.
When a new resource is created for this client the listener will be notified, carrying the new resource as the data argument.
- Parameters
client
: The client objectlistener
: The listener to be added
-
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.
The function pointed by
iterator will be called for each resource owned by the client. The user_data will be passed as the second argument of the iterator function. If the iterator function returns WL_ITERATOR_CONTINUE the iteration will continue, if it returns WL_ITERATOR_STOP it will stop.- Parameters
client
: The client objectiterator
: The iterator functionuser_data
: The user data pointer
Creating and destroying resources while iterating is safe, but new resources may or may not be picked up by the iterator.
Public Members
-
struct wl_connection *
connection
¶
-
struct wl_event_source *
source
¶
-
struct wl_display *
display
¶
-
struct wl_resource *
display_resource
¶
-
struct wl_map
objects
¶
-
struct wl_priv_signal
destroy_signal
¶
-
int
error
¶
-
struct wl_priv_signal
resource_created_signal
¶
-
void
-
struct
wl_display
Public Functions
-
struct wl_client *
wl_client_create
(struct wl_display *display, int fd)¶ Create a client for the given file descriptor.
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.- Return
- The new client object or NULL on failure.
- Parameters
display
: The display objectfd
: The file descriptor for the socket to the client
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.
-
struct wl_display *
wl_display_create
(void)¶ Create Wayland display object.
This creates the
wl_display object.- Return
- The Wayland display object. Null if failed to create
-
void
wl_display_destroy
(struct wl_display *display)¶ Destroy Wayland display object.
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.- Return
- None.
- Parameters
display
: The Wayland display object which should be destroyed.
-
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.
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.- Return
- None.
- Parameters
display
: The Wayland display object.filter
: The global filter funtion.data
: User data to be associated with the global filter.
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.
-
uint32_t
wl_display_get_serial
(struct wl_display *display)¶ Get the current serial number.
This function returns the most recent serial number, but does not increment it.
- Parameters
display
: The display object
-
uint32_t
wl_display_next_serial
(struct wl_display *display)¶ Get the next serial number.
This function increments the display serial number and returns the new value.
- Parameters
display
: The display object
-
void
wl_display_destroy_clients
(struct wl_display *display)¶ Destroy all clients connected to the display.
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.- Parameters
display
: The display object
-
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.
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.
- Return
- 0 if success. -1 if failed.
- Parameters
display
: Wayland display to which the socket should be added.sock_fd
: The existing socket file descriptor to be used
-
int
wl_display_add_socket
(struct wl_display *display, const char *name)¶ Add a socket to Wayland display for the clients to connect.
This adds a Unix socket to Wayland display which can be used by clients to connect to Wayland display.
- Return
- 0 if success. -1 if failed.
- Parameters
display
: Wayland display to which the socket should be added.name
: Name of the Unix socket.
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.
-
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 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.
errno is set on error.
- Return
- The protol logger object on success, NULL on failure.
- See
- wl_protocol_logger_destroy
- Parameters
display
: The display objectfunc
: The function to call to log a new protocol messageuser_data
: The user data pointer to pass to func
-
uint32_t *
wl_display_add_shm_format
(struct wl_display *display, uint32_t format)¶ Add support for a wl_shm pixel format.
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.
- Return
- A pointer to the wl_shm format that was added to the list or NULL if adding it to the list failed.
- Parameters
display
: The display objectformat
: The wl_shm pixel format to advertise
The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.
-
struct wl_list *
wl_display_get_client_list
(struct wl_display *display)¶ Get the list of currently connected clients.
This function returns a pointer to the list of clients currently connected to the display. You can iterate on the list by using the
wl_client_for_each macro. The returned value is valid for the lifetime of the display. You must not modify the returned list, but only access it.- Parameters
display
: The display object
Public Members
-
struct wl_event_loop *
loop
¶
-
int
run
¶
-
uint32_t
id
¶
-
uint32_t
serial
¶
-
struct wl_priv_signal
destroy_signal
¶
-
struct wl_priv_signal
create_client_signal
¶
-
wl_display_global_filter_func_t
global_filter
¶
-
void *
global_filter_data
¶
Private Functions
-
struct wl_array *
wl_display_get_additional_shm_formats
(struct wl_display *display)¶ Get list of additional wl_shm pixel formats.
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.- Parameters
display
: The display object
-
struct wl_client *
-
struct
wl_event_loop
¶ - #include <wayland-server-core.h>
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.
- See
- wl_event_source
Public Functions
-
struct wl_event_loop *
wl_event_loop_create
(void)¶ Create a new event loop context.
This creates a new event loop context. Initially this context is empty. Event sources need to be explicitly added to it.
- Return
- A new event loop context object.
Normally the event loop is run by calling wl_event_loop_dispatch() in a loop until the program terminates. Alternatively, an event loop can be embedded in another event loop by its file descriptor, see wl_event_loop_get_fd().
-
void
wl_event_loop_destroy
(struct wl_event_loop *loop)¶ Destroy an event loop context.
This emits the event loop destroy signal, closes the event loop file descriptor, and frees
loop
.- Parameters
loop
: The event loop to be destroyed.
If the event loop has existing sources, those cannot be safely removed afterwards. Therefore one must call wl_event_source_remove() on all event sources before destroying the event loop context.
-
void
wl_event_loop_dispatch_idle
(struct wl_event_loop *loop)¶ Dispatch the idle sources.
- See
- wl_event_loop_add_idle()
- Parameters
loop
: The event loop whose idle sources are dispatched.
-
int
wl_event_loop_dispatch
(struct wl_event_loop *loop, int timeout)¶ Wait for events and dispatch them.
All the associated event sources are polled. This function blocks until any event source delivers an event (idle sources excluded), or the timeout expires. A timeout of -1 disables the timeout, causing the function to block indefinitely. A timeout of zero causes the poll to always return immediately.
- Return
- 0 for success, -1 for polling error.
- Parameters
loop
: The event loop whose sources to wait for.timeout
: The polling timeout in milliseconds.
All idle sources are dispatched before blocking. An idle source is destroyed when it is dispatched. After blocking, all other ready sources are dispatched. Then, idle sources are dispatched again, in case the dispatched events created idle sources. Finally, all sources marked with wl_event_source_check() are dispatched in a loop until their dispatch functions all return zero.
-
int
wl_event_loop_get_fd
(struct wl_event_loop *loop)¶ Get the event loop file descriptor.
This function returns the aggregate file descriptor, that represents all the event sources (idle sources excluded) associated with the given event loop context. When any event source makes an event available, it will be reflected in the aggregate file descriptor.
- Return
- The aggregate file descriptor.
- Parameters
loop
: The event loop context.
When the aggregate file descriptor delivers an event, one can call wl_event_loop_dispatch() on the event loop context to dispatch all the available events.
-
void
wl_event_loop_add_destroy_listener
(struct wl_event_loop *loop, struct wl_listener *listener)¶ Register a destroy listener for an event loop context.
- See
- wl_listener
- Parameters
loop
: The event loop context whose destruction to listen for.listener
: The listener with the callback to be called.
-
struct wl_listener *
wl_event_loop_get_destroy_listener
(struct wl_event_loop *loop, wl_notify_func_t notify)¶ Get the listener struct for the specified callback.
- Return
- The wl_listener registered to the event loop context with the given callback pointer.
- Parameters
loop
: The event loop context to inspect.notify
: The destroy callback to find.
-
struct
wl_event_source
¶ - #include <wayland-server-core.h>
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.
Public Types
-
typedef int (*
wl_event_loop_fd_func_t
)(int fd, uint32_t mask, void *data)¶ File descriptor dispatch function type.
Functions of this type are used as callbacks for file descriptor events.
- Return
- 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.
- See
- wl_event_loop_add_fd()
- Parameters
fd
: The file descriptor delivering the event.mask
: Describes the kind of the event as a bitwise-or of:WL_EVENT_READABLE
,WL_EVENT_WRITABLE
,WL_EVENT_HANGUP
,WL_EVENT_ERROR
.data
: The user data argument of the related wl_event_loop_add_fd() call.
-
typedef int (*
wl_event_loop_timer_func_t
)(void *data)¶ Timer dispatch function type.
Functions of this type are used as callbacks for timer expiry.
- Return
- 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.
- See
- wl_event_loop_add_timer()
- Parameters
data
: The user data argument of the related wl_event_loop_add_timer() call.
-
typedef int (*
wl_event_loop_signal_func_t
)(int signal_number, void *data)¶ Signal dispatch function type.
Functions of this type are used as callbacks for (POSIX) signals.
- Return
- 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.
- See
- wl_event_loop_add_signal()
- Parameters
signal_number
:data
: The user data argument of the related wl_event_loop_add_signal() call.
-
typedef void (*
wl_event_loop_idle_func_t
)(void *data)¶ Idle task function type.
Functions of this type are used as callbacks before blocking in wl_event_loop_dispatch().
- See
- wl_event_loop_add_idle() wl_event_loop_dispatch()
- Parameters
data
: The user data argument of the related wl_event_loop_add_idle() call.
Public Functions
-
struct wl_event_source *
wl_event_loop_add_fd
(struct wl_event_loop *loop, int fd, uint32_t mask, wl_event_loop_fd_func_t func, void *data)¶ Create a file descriptor event source.
The given file descriptor is initially watched for the events given in
mask
. This can be changed as needed with wl_event_source_fd_update().- Return
- A new file descriptor event source.
- Parameters
loop
: The event loop that will process the new source.fd
: The file descriptor to watch.mask
: A bitwise-or of which events to watch for:WL_EVENT_READABLE
,WL_EVENT_WRITABLE
.func
: The file descriptor dispatch function.data
: User data.
If it is possible that program execution causes the file descriptor to be read while leaving the data in a buffer without actually processing it, it may be necessary to register the file descriptor source to be re-checked, see wl_event_source_check(). This will ensure that the dispatch function gets called even if the file descriptor is not readable or writable anymore. This is especially useful with IPC libraries that automatically buffer incoming data, possibly as a side-effect of other operations.
-
int
wl_event_source_fd_update
(struct wl_event_source *source, uint32_t mask)¶ Update a file descriptor source’s event mask.
This changes which events, readable and/or writable, cause the dispatch callback to be called on.
- Return
- 0 on success, -1 on failure.
- Parameters
source
: The file descriptor event source to update.mask
: The new mask, a bitwise-or of:WL_EVENT_READABLE
,WL_EVENT_WRITABLE
.
File descriptors are usually writable to begin with, so they do not need to be polled for writable until a write actually fails. When a write fails, the event mask can be changed to poll for readable and writable, delivering a dispatch callback when it is possible to write more. Once all data has been written, the mask can be changed to poll only for readable to avoid busy-looping on dispatch.
-
struct wl_event_source *
wl_event_loop_add_timer
(struct wl_event_loop *loop, wl_event_loop_timer_func_t func, void *data)¶ Create a timer event source.
The timer is initially disarmed. It needs to be armed with a call to
wl_event_source_timer_update() before it can trigger a dispatch call.- Return
- A new timer event source.
- Parameters
loop
: The event loop that will process the new source.func
: The timer dispatch function.data
: User data.
-
int
wl_event_source_timer_update
(struct wl_event_source *source, int ms_delay)¶ Arm or disarm a timer.
If the timeout is zero, the timer is disarmed.
- Return
- 0 on success, -1 on failure.
- Parameters
source
: The timer event source to modify.ms_delay
: The timeout in milliseconds.
If the timeout is non-zero, the timer is set to expire after the given timeout in milliseconds. When the timer expires, the dispatch function set with wl_event_loop_add_timer() is called once from wl_event_loop_dispatch(). If another dispatch is desired after another expiry, wl_event_source_timer_update() needs to be called again.
-
struct wl_event_source *
wl_event_loop_add_signal
(struct wl_event_loop *loop, int signal_number, wl_event_loop_signal_func_t func, void *data)¶ Create a POSIX signal event source.
This function blocks the normal delivery of the given signal in the calling thread, and creates a “watch” for it. Signal delivery no longer happens asynchronously, but by
wl_event_loop_dispatch() calling the dispatch callback functionfunc
.- Return
- A new signal event source.
- Parameters
loop
: The event loop that will process the new source.signal_number
: Number of the signal to watch for.func
: The signal dispatch function.data
: User data.
It is the caller’s responsibility to ensure that all other threads have also blocked the signal.
-
struct wl_event_source *
wl_event_loop_add_idle
(struct wl_event_loop *loop, wl_event_loop_idle_func_t func, void *data)¶ Create an idle task.
Idle tasks are dispatched before
wl_event_loop_dispatch() goes to sleep. See wl_event_loop_dispatch() for more details.- Return
- A new idle task (an event source).
- Parameters
loop
: The event loop that will process the new task.func
: The idle task dispatch function.data
: User data.
Idle tasks fire once, and are automatically destroyed right after the callback function has been called.
An idle task can be cancelled before the callback has been called by wl_event_source_remove(). Calling wl_event_source_remove() after or from within the callback results in undefined behaviour.
-
void
wl_event_source_check
(struct wl_event_source *source)¶ Mark event source to be re-checked.
This function permanently marks the event source to be re-checked after the normal dispatch of sources in
wl_event_loop_dispatch(). Re-checking will keep iterating over all such event sources until the dispatch function for them all returns zero.- Parameters
source
: The event source to be re-checked.
Re-checking is used on sources that may become ready to dispatch as a side-effect of dispatching themselves or other event sources, including idle sources. Re-checking ensures all the incoming events have been fully drained before wl_event_loop_dispatch() returns.
-
int
wl_event_source_remove
(struct wl_event_source *source)¶ Remove an event source from its event loop.
The event source is removed from the event loop it was created for, and is effectively destroyed. This invalidates
source
. The dispatch function of the source will no longer be called through this source.- Return
- Zero.
- Parameters
source
: The event source to be removed.
-
typedef int (*
-
struct
wl_global
¶ Public Members
-
struct wl_display *
display
¶
-
const struct wl_interface *
interface
¶
-
uint32_t
name
¶
-
uint32_t
version
¶
-
void *
data
¶
-
struct wl_display *
-
struct
wl_interface
- #include <wayland-util.h>
Protocol object interface.
A wl_interface describes the API of a protocol object defined in the Wayland protocol specification. The protocol implementation uses a wl_interface within its marshalling machinery for encoding client requests.
The
name
of a wl_interface is the name of the corresponding protocol interface, andversion
represents the version of the interface. The membersmethod_count
andevent_count
represent the number ofmethods
(requests) andevents
in the respective wl_message members.For example, consider a protocol interface
foo
, marked as version1
, with two requests and one event.<interface name="foo" version="1"> <request name="a"></request> <request name="b"></request> <event name="c"></event> </interface>
Given two wl_message arrays
foo_requests
andfoo_events
, a wl_interface forfoo
might be:struct wl_interface foo_interface = { "foo", 1, 2, foo_requests, 1, foo_events };
- Note
- The server side of the protocol may define interface implementation types that incorporate the term
interface
in their name. Take care to not confuse these server-sidestruct
s with a wl_interface variable whose name also ends ininterface
. For example, while the server may define a typestruct wl_foo_interface
, the client may define astruct wl_interface wl_foo_interface
. - See
- wl_message
- See
- wl_proxy
- See
- Interfaces
- See
- Versioning
Public Members
-
const char *
name
Interface name.
-
int
version
Interface version.
-
int
method_count
Number of methods (requests)
-
const struct wl_message *
methods
Method (request) signatures.
-
int
event_count
Number of events.
-
const struct wl_message *
events
Event signatures.
-
class
wl_list
- #include <wayland-util.h>
Doubly-linked list.
On its own, an instance of
struct wl_list
represents the sentinel head of a doubly-linked list, and must be initialized using wl_list_init(). When empty, the list head’snext
andprev
members point to the list head itself, otherwisenext
references the first element in the list, andprev
refers to the last element in the list.Use the
struct wl_list
type to represent both the list head and the links between elements within the list. Use wl_list_empty() to determine if the list is empty in O(1).All elements in the list must be of the same type. The element type must have a
struct wl_list
member, often namedlink
by convention. Prior to insertion, there is no need to initialize an element’slink
- invoking wl_list_init() on an individual list element’sstruct wl_list
member is unnecessary if the very next operation is wl_list_insert(). However, a common idiom is to initialize an element’slink
prior to removal - ensure safety by invoking wl_list_init() before wl_list_remove().Consider a list reference
struct wl_list foo_list
, an element type asstruct element
, and an element’s link member asstruct wl_list link
.The following code initializes a list and adds three elements to it.
struct wl_list foo_list; struct element { int foo; struct wl_list link; }; struct element e1, e2, e3; wl_list_init(&foo_list); wl_list_insert(&foo_list, &e1.link); // e1 is the first element wl_list_insert(&foo_list, &e2.link); // e2 is now the first element wl_list_insert(&e2.link, &e3.link); // insert e3 after e2
The list now looks like [e2, e3, e1].
The
wl_list
API provides some iterator macros. For example, to iterate a list in ascending order:struct element *e; wl_list_for_each(e, foo_list, link) { do_something_with_element(e); }
See the documentation of each iterator for details.
Public Functions
-
void
wl_list_init
(struct wl_list *list) Initializes the list.
- Parameters
list
: List to initialize
-
void
wl_list_insert
(struct wl_list *list, struct wl_list *elm) Inserts an element into the list, after the element represented by
list
.When
list
is a reference to the list itself (the head), set the containing struct ofelm
as the first element in the list.- Note
- If
elm
is already part of a list, inserting it again will lead to list corruption. - Parameters
list
: List element after which the new element is insertedelm
: Link of the containing struct to insert into the list
-
void
wl_list_remove
(struct wl_list *elm) Removes an element from the list.
- Note
- This operation leaves
elm
in an invalid state. - Parameters
elm
: Link of the containing struct to remove from the list
-
int
wl_list_length
(const struct wl_list *list) Determines the length of the list.
- Note
- This is an O(n) operation.
- Return
- Number of elements in the list
- Parameters
list
: List whose length is to be determined
-
int
wl_list_empty
(const struct wl_list *list) Determines if the list is empty.
- Return
- 1 if empty, or 0 if not empty
- Parameters
list
: List whose emptiness is to be determined
-
void
wl_list_insert_list
(struct wl_list *list, struct wl_list *other) Inserts all of the elements of one list into another, after the element represented by
list
.- Note
- This leaves
other
in an invalid state. - Parameters
list
: List element after which the other list elements will be insertedother
: List of elements to insert
Related
-
wl_list_for_each
(pos, head, member)¶ Iterates over a list.
This macro expresses a for-each iterator for wl_list. Given a list and wl_list link member name (often named
link
by convention), this macro assigns each element in the list topos
, which can then be referenced in a trailing code block. For example, given a wl_list ofstruct message
elements:struct message { char *contents; wl_list link; }; struct wl_list *message_list; // Assume message_list now "contains" many messages struct message *m; wl_list_for_each(m, message_list, link) { do_something_with_message(m); }
- Parameters
pos
: Cursor that each list element will be assigned tohead
: Head of the list to iterate overmember
: Name of the link member within the element struct
-
wl_list_for_each_safe
(pos, tmp, head, member)¶ Iterates over a list, safe against removal of the list element.
- Note
- Only removal of the current element,
pos
, is safe. Removing any other element during traversal may lead to a loop malfunction. - See
- wl_list_for_each()
- Parameters
pos
: Cursor that each list element will be assigned totmp
: Temporary pointer of the same type aspos
head
: Head of the list to iterate overmember
: Name of the link member within the element struct
-
wl_list_for_each_reverse
(pos, head, member)¶ Iterates backwards over a list.
- See
- wl_list_for_each()
- Parameters
pos
: Cursor that each list element will be assigned tohead
: Head of the list to iterate overmember
: Name of the link member within the element struct
-
wl_list_for_each_reverse_safe
(pos, tmp, head, member)¶ Iterates backwards over a list, safe against removal of the list element.
- Note
- Only removal of the current element,
pos
, is safe. Removing any other element during traversal may lead to a loop malfunction. - See
- wl_list_for_each()
- Parameters
pos
: Cursor that each list element will be assigned totmp
: Temporary pointer of the same type aspos
head
: Head of the list to iterate overmember
: Name of the link member within the element struct
-
void
-
class
wl_listener
¶ - #include <wayland-server-core.h>
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);
- See
- wl_signal
-
struct
wl_message
- #include <wayland-util.h>
Protocol message signature.
A wl_message describes the signature of an actual protocol message, such as a request or event, that adheres to the Wayland protocol wire format. The protocol implementation uses a wl_message within its demarshal machinery for decoding messages between a compositor and its clients. In a sense, a wl_message is to a protocol message like a class is to an object.
The
name
of a wl_message is the name of the corresponding protocol message.The
signature
is an ordered list of symbols representing the data types of message arguments and, optionally, a protocol version and indicators for nullability. A leading integer in thesignature
indicates the since version of the protocol message. A?
preceding a data type symbol indicates that the following argument type is nullable. While it is a protocol violation to send messages with non-nullable arguments set toNULL
, event handlers in clients might still get called with non-nullable object arguments set toNULL
. This can happen when the client destroyed the object being used as argument on its side and an event referencing that object was sent before the server knew about its destruction. As this race cannot be prevented, clients should - as a general rule - program their event handlers such that they can handle object arguments declared non-nullable beingNULL
gracefully.When no arguments accompany a message,
signature
is an empty string.Symbols:
i
: intu
: uintf
: fixeds
: stringo
: objectn
: new_ida
: arrayh
: fd?
: following argument is nullable
While demarshaling primitive arguments is straightforward, when demarshaling messages containing
object
ornew_id
arguments, the protocol implementation often must determine the type of the object. Thetypes
of a wl_message is an array of wl_interface references that correspond too
andn
arguments insignature
, withNULL
placeholders for arguments with non-object types.Consider the protocol event wl_display
delete_id
that has a singleuint
argument. The wl_message is:{ "delete_id", "u", [NULL] }
Here, the message
name
is"delete_id"
, thesignature
is"u"
, and the argumenttypes
is[NULL]
, indicating that theuint
argument has no corresponding wl_interface since it is a primitive argument.In contrast, consider a
wl_foo
interface supporting protocol requestbar
that has existed since version 2, and has two arguments: auint
and an object of typewl_baz_interface
that may beNULL
. Such awl_message
might be:{ "bar", "2u?o", [NULL, &wl_baz_interface] }
Here, the message
name
is"bar"
, and thesignature
is"2u?o"
. Notice how the2
indicates the protocol version, theu
indicates the first argument type isuint
, and the?o
indicates that the second argument is an object that may beNULL
. Lastly, the argumenttypes
array indicates that no wl_interface corresponds to the first argument, while the typewl_baz_interface
corresponds to the second argument.- See
- wl_argument
- See
- wl_interface
- See
- Wire Format
Public Members
-
const char *
name
Message name.
-
const char *
signature
Message signature.
-
const struct wl_interface **
types
Object argument interfaces.
-
class
wl_object
- #include <wayland-server.h>
A protocol object.
A
wl_object
is an opaque struct identifying the protocol object underlying awl_proxy
orwl_resource
.- Note
- Functions accessing a
wl_object
are not normally used by client code. Clients should normally use the higher level interface generated by the scanner to interact with compositor objects.
-
struct
wl_protocol_logger
¶ Public Functions
-
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 wl_display_add_protocol_logger. The logger object becomes invalid after calling this function.
-
void
-
struct
wl_protocol_logger_message
¶ - #include <wayland-server-core.h>
Public Members
-
struct wl_resource *
resource
¶
-
int
message_opcode
¶
-
const struct wl_message *
message
¶
-
int
arguments_count
¶
-
const union wl_argument *
arguments
¶
-
struct wl_resource *
-
struct
wl_resource
¶ - #include <wayland-server.h>
Public Functions
-
const char *
wl_resource_get_class
(struct wl_resource *resource)¶ Retrieve the interface name (class) of a resource object.
- Parameters
resource
: The resource 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.
Listeners added with
wl_client_add_resource_created_listener will be notified at the end of this function.- 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.
-
const char *
-
struct
wl_resource_iterator_context
¶
-
struct
wl_shm_buffer
¶ Public Functions
-
void *
wl_shm_buffer_get_data
(struct wl_shm_buffer *buffer)¶ Get a pointer to the memory for the SHM buffer.
Returns a pointer which can be used to read the data contained in the given SHM buffer.
- Parameters
buffer
: The buffer object
As this buffer is memory-mapped, reading from it may generate SIGBUS signals. This can happen if the client claims that the buffer is larger than it is or if something truncates the underlying file. To prevent this signal from causing the compositor to crash you should call wl_shm_buffer_begin_access and wl_shm_buffer_end_access around code that reads from the memory.
-
struct wl_shm_pool *
wl_shm_buffer_ref_pool
(struct wl_shm_buffer *buffer)¶ Get a reference to a shm_buffer’s shm_pool.
Returns a pointer to a buffer’s shm_pool and increases the shm_pool refcount.
- Parameters
buffer
: The buffer object
The compositor must remember to call wl_shm_pool_unref when it no longer needs the reference to ensure proper destruction of the pool.
-
void
wl_shm_buffer_begin_access
(struct wl_shm_buffer *buffer)¶ Mark that the given SHM buffer is about to be accessed.
An SHM buffer is a memory-mapped file given by the client. According to POSIX, reading from a memory-mapped region that extends off the end of the file will cause a SIGBUS signal to be generated. Normally this would cause the compositor to terminate. In order to make the compositor robust against clients that change the size of the underlying file or lie about its size, you should protect access to the buffer by calling this function before reading from the memory and call wl_shm_buffer_end_access afterwards. This will install a signal handler for SIGBUS which will prevent the compositor from crashing.
- Parameters
buffer
: The SHM buffer
After calling this function the signal handler will remain installed for the lifetime of the compositor process. Note that this function will not work properly if the compositor is also installing its own handler for SIGBUS.
If a SIGBUS signal is received for an address within the range of the SHM pool of the given buffer then the client will be sent an error event when wl_shm_buffer_end_access is called. If the signal is for an address outside that range then the signal handler will reraise the signal which would will likely cause the compositor to terminate.
It is safe to nest calls to these functions as long as the nested calls are all accessing the same buffer. The number of calls to wl_shm_buffer_end_access must match the number of calls to wl_shm_buffer_begin_access. These functions are thread-safe and it is allowed to simultaneously access different buffers or the same buffer from multiple threads.
-
void
wl_shm_buffer_end_access
(struct wl_shm_buffer *buffer)¶ Ends the access to a buffer started by wl_shm_buffer_begin_access.
This should be called after wl_shm_buffer_begin_access once the buffer is no longer being accessed. If a SIGBUS signal was generated in-between these two calls then the resource for the given buffer will be sent an error.
- Parameters
buffer
: The SHM buffer
Public Members
-
struct wl_resource *
resource
¶
-
int32_t
width
¶
-
int32_t
height
¶
-
int32_t
stride
¶
-
uint32_t
format
¶
-
int
offset
¶
-
struct wl_shm_pool *
pool
¶
-
void *
-
struct
wl_shm_pool
¶ Public Functions
-
void
wl_shm_pool_unref
(struct wl_shm_pool *pool)¶ Unreference a shm_pool.
Drops a reference to a
wl_shm_pool object.- Parameters
pool
: The pool object
This is only necessary if the compositor has explicitly taken a reference with wl_shm_buffer_ref_pool(), otherwise the pool will be automatically destroyed when appropriate.
-
void
-
struct
wl_shm_sigbus_data
¶
-
class
wl_signal
¶ - #include <wayland-server-core.h>
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).
- See
- wl_listener for more information on using wl_signal
Public Functions
-
static void
wl_signal_init
(struct wl_signal *signal)¶ Initialize a new wl_signal for use.
- Parameters
signal
: The signal that will be initialized
-
static 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 listenerlistener
: The listener to add
-
static struct wl_listener *
wl_signal_get
(struct wl_signal *signal, wl_notify_func_t notify)¶ Gets the listener struct for the specified callback.
- Return
- the list item that corresponds to the specified listener, or NULL if none was found
- Parameters
signal
: The signal that contains the specified listenernotify
: The listener that is the target of this search
-
struct
wl_socket
¶
-
file
event-loop.c
- #include <stddef.h>#include <stdio.h>#include <errno.h>#include <signal.h>#include <stdlib.h>#include <stdint.h>#include <stdbool.h>#include <string.h>#include <fcntl.h>#include <sys/socket.h>#include <sys/un.h>#include <sys/epoll.h>#include <sys/signalfd.h>#include <sys/timerfd.h>#include <unistd.h>#include “wayland-util.h”#include “wayland-private.h”#include <stdarg.h>#include “/home/mvlad/src/wayland/src/wayland-server-core.h”#include “wayland-os.h”
Functions
-
static int
wl_event_source_fd_dispatch
(struct wl_event_source *source, struct epoll_event *ep)¶
-
static struct wl_event_source *
add_source
(struct wl_event_loop *loop, struct wl_event_source *source, uint32_t mask, void *data)¶
-
static int
wl_event_source_timer_dispatch
(struct wl_event_source *source, struct epoll_event *ep)¶
-
static int
wl_event_source_signal_dispatch
(struct wl_event_source *source, struct epoll_event *ep)¶
-
static void
wl_event_loop_process_destroy_list
(struct wl_event_loop *loop)¶
-
static bool
post_dispatch_check
(struct wl_event_loop *loop)¶
Variables
-
struct wl_event_source_interface
fd_source_interface
= {wl_event_source_fd_dispatch}¶
-
struct wl_event_source_interface
timer_source_interface
= {wl_event_source_timer_dispatch}¶
-
struct wl_event_source_interface
signal_source_interface
= {wl_event_source_signal_dispatch,}¶
-
struct wl_event_source_interface
idle_source_interface
= { NULL,}¶
-
static int
-
file
wayland-server-core.h
- #include <sys/types.h>#include <stdint.h>#include <stdbool.h>#include “wayland-util.h”#include “wayland-version.h”
Defines
-
wl_client_for_each
(client, list)¶ Iterate over a list of clients.
-
wl_resource_for_each
(resource, list)¶
-
wl_resource_for_each_safe
(resource, tmp, list)¶
Typedefs
-
typedef void (*
wl_notify_func_t
)(struct wl_listener *listener, void *data)¶
-
typedef void (*
wl_global_bind_func_t
)(struct wl_client *client, void *data, uint32_t version, uint32_t id)¶
-
typedef bool (*
wl_display_global_filter_func_t
)(const struct wl_client *client, const struct wl_global *global, void *data)¶ A filter function for wl_global objects.
A filter function enables the server to decide which globals to advertise to each client.
- Parameters
client
: The client objectglobal
: The global object to show or hidedata
: The user data pointer
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.
-
typedef enum wl_iterator_result (*
wl_client_for_each_resource_iterator_func_t
)(struct wl_resource *resource, void *user_data)¶
-
typedef void (*
wl_resource_destroy_func_t
)(struct wl_resource *resource)¶
-
typedef void (*
wl_protocol_logger_func_t
)(void *user_data, enum wl_protocol_logger_type direction, const struct wl_protocol_logger_message *message)¶
Enums
Functions
-
struct wl_event_loop *
wl_event_loop_create
(void)
-
void
wl_event_loop_destroy
(struct wl_event_loop *loop)
-
struct wl_event_source *
wl_event_loop_add_fd
(struct wl_event_loop *loop, int fd, uint32_t mask, wl_event_loop_fd_func_t func, void *data)
-
int
wl_event_source_fd_update
(struct wl_event_source *source, uint32_t mask)
-
struct wl_event_source *
wl_event_loop_add_timer
(struct wl_event_loop *loop, wl_event_loop_timer_func_t func, void *data)
-
struct wl_event_source *
wl_event_loop_add_signal
(struct wl_event_loop *loop, int signal_number, wl_event_loop_signal_func_t func, void *data)
-
int
wl_event_source_timer_update
(struct wl_event_source *source, int ms_delay)
-
int
wl_event_source_remove
(struct wl_event_source *source)
-
void
wl_event_source_check
(struct wl_event_source *source)
-
int
wl_event_loop_dispatch
(struct wl_event_loop *loop, int timeout)
-
void
wl_event_loop_dispatch_idle
(struct wl_event_loop *loop)
-
struct wl_event_source *
wl_event_loop_add_idle
(struct wl_event_loop *loop, wl_event_loop_idle_func_t func, void *data)
-
int
wl_event_loop_get_fd
(struct wl_event_loop *loop)
-
void
wl_event_loop_add_destroy_listener
(struct wl_event_loop *loop, struct wl_listener *listener)
-
struct wl_listener *
wl_event_loop_get_destroy_listener
(struct wl_event_loop *loop, wl_notify_func_t notify)
-
struct wl_display *
wl_display_create
(void)
-
void
wl_display_destroy
(struct wl_display *display)
-
struct wl_event_loop *
wl_display_get_event_loop
(struct wl_display *display)¶
-
int
wl_display_add_socket
(struct wl_display *display, const char *name)
-
const char *
wl_display_add_socket_auto
(struct wl_display *display)¶
-
int
wl_display_add_socket_fd
(struct wl_display *display, int sock_fd)
-
void
wl_display_terminate
(struct wl_display *display)¶
-
void
wl_display_run
(struct wl_display *display)¶
-
void
wl_display_flush_clients
(struct wl_display *display)¶
-
void
wl_display_destroy_clients
(struct wl_display *display)
-
uint32_t
wl_display_get_serial
(struct wl_display *display)
-
uint32_t
wl_display_next_serial
(struct wl_display *display)
-
void
wl_display_add_destroy_listener
(struct wl_display *display, struct wl_listener *listener)¶
-
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, listener will be notified, carrying a pointer to the new wl_client object.
wl_client_create wl_display wl_listener
- Parameters
display
: The display objectlistener
: Signal handler object
-
struct wl_listener *
wl_display_get_destroy_listener
(struct wl_display *display, wl_notify_func_t notify)¶
-
struct wl_global *
wl_global_create
(struct wl_display *display, const struct wl_interface *interface, int version, void *data, wl_global_bind_func_t bind)¶
-
void
wl_display_set_global_filter
(struct wl_display *display, wl_display_global_filter_func_t filter, void *data)
-
const struct wl_interface *
wl_global_get_interface
(const struct wl_global *global)¶
-
struct wl_client *
wl_client_create
(struct wl_display *display, int fd)
-
struct wl_list *
wl_display_get_client_list
(struct wl_display *display)
-
void
wl_client_flush
(struct wl_client *client)
-
void
wl_client_get_credentials
(struct wl_client *client, pid_t *pid, uid_t *uid, gid_t *gid)
-
int
wl_client_get_fd
(struct wl_client *client)
-
void
wl_client_add_destroy_listener
(struct wl_client *client, struct wl_listener *listener)¶
-
struct wl_listener *
wl_client_get_destroy_listener
(struct wl_client *client, wl_notify_func_t notify)¶
-
struct wl_resource *
wl_client_get_object
(struct wl_client *client, uint32_t id)
-
void
wl_client_post_implementation_error
(struct wl_client *client, const char *msg, ...)
-
void
wl_client_add_resource_created_listener
(struct wl_client *client, struct wl_listener *listener)
-
void
wl_client_for_each_resource
(struct wl_client *client, wl_client_for_each_resource_iterator_func_t iterator, void *user_data)
-
void
wl_resource_post_event
(struct wl_resource *resource, uint32_t opcode, ...)¶
-
void
wl_resource_post_event_array
(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)¶
-
void
wl_resource_queue_event
(struct wl_resource *resource, uint32_t opcode, ...)¶
-
void
wl_resource_queue_event_array
(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)¶
-
void
wl_resource_post_error
(struct wl_resource *resource, uint32_t code, const char *msg, ...)¶
-
void
wl_resource_post_no_memory
(struct wl_resource *resource)¶
-
struct wl_display *
wl_client_get_display
(struct wl_client *client)
-
struct wl_resource *
wl_resource_create
(struct wl_client *client, const struct wl_interface *interface, int version, uint32_t id)
-
void
wl_resource_set_implementation
(struct wl_resource *resource, const void *implementation, void *data, wl_resource_destroy_func_t destroy)¶
-
void
wl_resource_set_dispatcher
(struct wl_resource *resource, wl_dispatcher_func_t dispatcher, const void *implementation, void *data, wl_resource_destroy_func_t destroy)¶
-
void
wl_resource_destroy
(struct wl_resource *resource)¶
-
uint32_t
wl_resource_get_id
(struct wl_resource *resource)¶
-
struct wl_list *
wl_resource_get_link
(struct wl_resource *resource)¶
-
struct wl_resource *
wl_resource_from_link
(struct wl_list *resource)¶
-
struct wl_resource *
wl_resource_find_for_client
(struct wl_list *list, struct wl_client *client)¶
-
struct wl_client *
wl_resource_get_client
(struct wl_resource *resource)¶
-
void
wl_resource_set_user_data
(struct wl_resource *resource, void *data)¶
-
void *
wl_resource_get_user_data
(struct wl_resource *resource)¶
-
int
wl_resource_get_version
(struct wl_resource *resource)¶
-
void
wl_resource_set_destructor
(struct wl_resource *resource, wl_resource_destroy_func_t destroy)¶
-
int
wl_resource_instance_of
(struct wl_resource *resource, const struct wl_interface *interface, const void *implementation)¶
-
const char *
wl_resource_get_class
(struct wl_resource *resource)
-
void
wl_resource_add_destroy_listener
(struct wl_resource *resource, struct wl_listener *listener)¶
-
struct wl_listener *
wl_resource_get_destroy_listener
(struct wl_resource *resource, wl_notify_func_t notify)¶
-
struct wl_shm_buffer *
wl_shm_buffer_get
(struct wl_resource *resource)¶
-
void
wl_shm_buffer_begin_access
(struct wl_shm_buffer *buffer)
-
void
wl_shm_buffer_end_access
(struct wl_shm_buffer *buffer)
-
void *
wl_shm_buffer_get_data
(struct wl_shm_buffer *buffer)
-
int32_t
wl_shm_buffer_get_stride
(struct wl_shm_buffer *buffer)¶
-
uint32_t
wl_shm_buffer_get_format
(struct wl_shm_buffer *buffer)¶
-
int32_t
wl_shm_buffer_get_width
(struct wl_shm_buffer *buffer)¶
-
int32_t
wl_shm_buffer_get_height
(struct wl_shm_buffer *buffer)¶
-
struct wl_shm_pool *
wl_shm_buffer_ref_pool
(struct wl_shm_buffer *buffer)
-
void
wl_shm_pool_unref
(struct wl_shm_pool *pool)
-
int
wl_display_init_shm
(struct wl_display *display)¶
-
uint32_t *
wl_display_add_shm_format
(struct wl_display *display, uint32_t format)
-
struct wl_shm_buffer *
wl_shm_buffer_create
(struct wl_client *client, uint32_t id, int32_t width, int32_t height, int32_t stride, uint32_t format)¶
-
void
wl_log_set_handler_server
(wl_log_func_t handler)¶
-
struct wl_protocol_logger *
wl_display_add_protocol_logger
(struct wl_display *display, wl_protocol_logger_func_t, void *user_data)
-
void
wl_protocol_logger_destroy
(struct wl_protocol_logger *logger)
-
-
file
wayland-server.c
- #include <stdlib.h>#include <stdint.h>#include <stddef.h>#include <stdio.h>#include <stdarg.h>#include <stdbool.h>#include <errno.h>#include <string.h>#include <unistd.h>#include <sys/socket.h>#include <sys/un.h>#include <dlfcn.h>#include <assert.h>#include <sys/time.h>#include <fcntl.h>#include <sys/file.h>#include <sys/stat.h>#include “wayland-util.h”#include “wayland-private.h”#include “wayland-server.h”#include “wayland-os.h”
Functions
-
static void
log_closure
(struct wl_resource *resource, struct wl_closure *closure, int send)¶
-
static bool
verify_objects
(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)¶
-
static void
handle_array
(struct wl_resource *resource, uint32_t opcode, union wl_argument *args, int (*send_func)(struct wl_closure *, struct wl_connection *))¶
-
void
wl_resource_post_event_array
(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)
-
void
wl_resource_post_event
(struct wl_resource *resource, uint32_t opcode, ...)
-
void
wl_resource_queue_event_array
(struct wl_resource *resource, uint32_t opcode, union wl_argument *args)
-
void
wl_resource_queue_event
(struct wl_resource *resource, uint32_t opcode, ...)
-
static void
wl_resource_post_error_vargs
(struct wl_resource *resource, uint32_t code, const char *msg, va_list argp)¶
-
void
wl_resource_post_error
(struct wl_resource *resource, uint32_t code, const char *msg, ...)
-
static int
wl_client_connection_data
(int fd, uint32_t mask, void *data)¶
-
static int
bind_display
(struct wl_client *client, struct wl_display *display)¶
-
void
wl_client_post_no_memory
(struct wl_client *client)
-
void
wl_resource_post_no_memory
(struct wl_resource *resource)
-
static 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.
-
static enum wl_iterator_result
destroy_resource
(void *element, void *data, uint32_t flags)¶
-
void
wl_resource_destroy
(struct wl_resource *resource)
-
uint32_t
wl_resource_get_id
(struct wl_resource *resource)
-
struct wl_list *
wl_resource_get_link
(struct wl_resource *resource)
-
struct wl_resource *
wl_resource_from_link
(struct wl_list *link)
-
struct wl_resource *
wl_resource_find_for_client
(struct wl_list *list, struct wl_client *client)
-
struct wl_client *
wl_resource_get_client
(struct wl_resource *resource)
-
void
wl_resource_set_user_data
(struct wl_resource *resource, void *data)
-
void *
wl_resource_get_user_data
(struct wl_resource *resource)
-
int
wl_resource_get_version
(struct wl_resource *resource)
-
void
wl_resource_set_destructor
(struct wl_resource *resource, wl_resource_destroy_func_t destroy)
-
int
wl_resource_instance_of
(struct wl_resource *resource, const struct wl_interface *interface, const void *implementation)
-
void
wl_resource_add_destroy_listener
(struct wl_resource *resource, struct wl_listener *listener)
-
struct wl_listener *
wl_resource_get_destroy_listener
(struct wl_resource *resource, wl_notify_func_t notify)
-
void
wl_client_add_destroy_listener
(struct wl_client *client, struct wl_listener *listener)
-
struct wl_listener *
wl_client_get_destroy_listener
(struct wl_client *client, wl_notify_func_t notify)
-
void
wl_client_destroy
(struct wl_client *client)
-
static void
registry_bind
(struct wl_client *client, struct wl_resource *resource, uint32_t name, const char *interface, uint32_t version, uint32_t id)¶
-
static void
display_sync
(struct wl_client *client, struct wl_resource *resource, uint32_t id)¶
-
static void
unbind_resource
(struct wl_resource *resource)¶
-
static void
display_get_registry
(struct wl_client *client, struct wl_resource *resource, uint32_t id)¶
-
static void
destroy_client_display_resource
(struct wl_resource *resource)¶
-
struct wl_global *
wl_global_create
(struct wl_display *display, const struct wl_interface *interface, int version, void *data, wl_global_bind_func_t bind)
-
void
wl_global_destroy
(struct wl_global *global)
-
const struct wl_interface *
wl_global_get_interface
(const struct wl_global *global)
-
void *
wl_global_get_user_data
(const struct wl_global *global)
-
struct wl_event_loop *
wl_display_get_event_loop
(struct wl_display *display)
-
void
wl_display_terminate
(struct wl_display *display)
-
void
wl_display_run
(struct wl_display *display)
-
void
wl_display_flush_clients
(struct wl_display *display)
-
static int
socket_data
(int fd, uint32_t mask, void *data)¶
-
static int
_wl_display_add_socket
(struct wl_display *display, struct wl_socket *s)¶
-
const char *
wl_display_add_socket_auto
(struct wl_display *display)
-
void
wl_display_add_destroy_listener
(struct wl_display *display, struct wl_listener *listener)
-
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, listener will be notified, carrying a pointer to the new wl_client object.
wl_client_create wl_display wl_listener
- Parameters
display
: The display objectlistener
: Signal handler object
-
struct wl_listener *
wl_display_get_destroy_listener
(struct wl_display *display, wl_notify_func_t notify)
-
void
wl_resource_set_implementation
(struct wl_resource *resource, const void *implementation, void *data, wl_resource_destroy_func_t destroy)
-
void
wl_resource_set_dispatcher
(struct wl_resource *resource, wl_dispatcher_func_t dispatcher, const void *implementation, void *data, wl_resource_destroy_func_t destroy)
-
void
wl_log_set_handler_server
(wl_log_func_t handler)
-
static enum wl_iterator_result
resource_iterator_helper
(void *res, void *user_data, uint32_t flags)¶
-
static void
-
file
wayland-server.h
- #include <stdint.h>#include “wayland-server-core.h”#include “wayland-server-protocol.h”
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.
Functions
-
uint32_t
wl_client_add_resource
(struct wl_client *client, struct wl_resource *resource)¶
-
struct wl_resource *
wl_client_add_object
(struct wl_client *client, const struct wl_interface *interface, const void *implementation, uint32_t id, void *data)¶
-
struct wl_resource *
wl_client_new_object
(struct wl_client *client, const struct wl_interface *interface, const void *implementation, void *data)¶
-
struct wl_global *
wl_display_add_global
(struct wl_display *display, const struct wl_interface *interface, void *data, wl_global_bind_func_t bind)¶
-
void
wl_display_remove_global
(struct wl_display *display, struct wl_global *global)¶
-
file
wayland-shm.c
- #include <stdbool.h>#include <stdio.h>#include <stdlib.h>#include <stdint.h>#include <string.h>#include <sys/mman.h>#include <unistd.h>#include <assert.h>#include <signal.h>#include <pthread.h>#include <errno.h>#include “wayland-util.h”#include “wayland-private.h”#include “wayland-server.h”
Defines
-
_GNU_SOURCE
Functions
-
static void
shm_pool_finish_resize
(struct wl_shm_pool *pool)¶
-
static void
shm_pool_unref
(struct wl_shm_pool *pool, bool external)¶
-
static void
destroy_buffer
(struct wl_resource *resource)¶
-
static void
shm_buffer_destroy
(struct wl_client *client, struct wl_resource *resource)¶
-
static void
shm_pool_create_buffer
(struct wl_client *client, struct wl_resource *resource, uint32_t id, int32_t offset, int32_t width, int32_t height, int32_t stride, uint32_t format)¶
-
static void
destroy_pool
(struct wl_resource *resource)¶
-
static void
shm_pool_destroy
(struct wl_client *client, struct wl_resource *resource)¶
-
static void
shm_pool_resize
(struct wl_client *client, struct wl_resource *resource, int32_t size)¶
-
static void
shm_create_pool
(struct wl_client *client, struct wl_resource *resource, uint32_t id, int fd, int32_t size)¶
-
int
wl_display_init_shm
(struct wl_display *display)
-
struct wl_shm_buffer *
wl_shm_buffer_get
(struct wl_resource *resource)
-
int32_t
wl_shm_buffer_get_stride
(struct wl_shm_buffer *buffer)
-
uint32_t
wl_shm_buffer_get_format
(struct wl_shm_buffer *buffer)
-
int32_t
wl_shm_buffer_get_width
(struct wl_shm_buffer *buffer)
-
int32_t
wl_shm_buffer_get_height
(struct wl_shm_buffer *buffer)
-
static void
reraise_sigbus
(void)¶
-
static void
sigbus_handler
(int signum, siginfo_t *info, void *context)¶
-
static void
destroy_sigbus_data
(void *data)¶
-
static void
init_sigbus_data_key
(void)¶
Variables
-
pthread_once_t
wl_shm_sigbus_once
= PTHREAD_ONCE_INIT¶
-
pthread_key_t
wl_shm_sigbus_data_key
¶
-
struct sigaction
wl_shm_old_sigbus_action
¶
-
const struct wl_buffer_interface
shm_buffer_interface
= {shm_buffer_destroy}¶
-
const struct wl_shm_pool_interface
shm_pool_interface
= {shm_pool_create_buffer,shm_pool_destroy,shm_pool_resize}¶
-
const struct wl_shm_interface
shm_interface
= {shm_create_pool}¶
-
-
file
wayland-util.h
- #include <math.h>#include <stddef.h>#include <inttypes.h>#include <stdarg.h>
Utility classes, functions, and macros.
Defines
-
WL_EXPORT
¶ Visibility attribute.
-
WL_DEPRECATED
¶ Deprecated attribute.
-
WL_PRINTF
(x, y)¶ Printf-style argument attribute.
- See
- https://gcc.gnu.org/onlinedocs/gcc-3.2.1/gcc/Function-Attributes.html
- Parameters
x
: Ordinality of the format string argumenty
: Ordinality of the argument to check against the format string
-
wl_container_of
(ptr, sample, member)¶ Retrieves a pointer to a containing struct, given a member name.
This macro allows “conversion” from a pointer to a member to its containing struct. This is useful if you have a contained item like a wl_list, wl_listener, or wl_signal, provided via a callback or other means, and would like to retrieve the struct that contains it.
To demonstrate, the following example retrieves a pointer to
example_container
given only itsdestroy_listener
member:struct example_container { struct wl_listener destroy_listener; // other members... }; void example_container_destroy(struct wl_listener *listener, void *data) { struct example_container *ctr; ctr = wl_container_of(listener, ctr, destroy_listener); // destroy ctr... }
- Note
sample
need not be a valid pointer. A null or uninitialised pointer is sufficient.- Return
- The container for the specified pointer
- Parameters
ptr
: Valid pointer to the contained membersample
: Pointer to a struct whose type containsptr
member
: Named location ofptr
within thesample
type
Typedefs
-
typedef int32_t
wl_fixed_t
Fixed-point number.
A
wl_fixed_t
is a 24.8 signed fixed-point number with a sign bit, 23 bits of integer precision and 8 bits of decimal precision. Considerwl_fixed_t
as an opaque struct with methods that facilitate conversion to and fromdouble
andint
types.
-
typedef int (*
wl_dispatcher_func_t
)(const void *, void *, uint32_t, const struct wl_message *, union wl_argument *) Dispatcher function type alias.
A dispatcher is a function that handles the emitting of callbacks in client code. For programs directly using the C library, this is done by using libffi to call function pointers. When binding to languages other than C, dispatchers provide a way to abstract the function calling process to be friendlier to other function calling systems.
A dispatcher takes five arguments: The first is the dispatcher-specific implementation associated with the target object. The second is the object upon which the callback is being invoked (either wl_proxy or wl_resource). The third and fourth arguments are the opcode and the wl_message corresponding to the callback. The final argument is an array of arguments received from the other process via the wire protocol.
- Return
- 0 on success, or -1 on failure
- Parameters
const void *
: Dispatcher-specific implementation datavoid *
: Callback invocation target (wl_proxy orwl_resource
)uint32_t
: Callback opcodeconst struct wl_message *
: Callback message signatureunion wl_argument *
: Array of received arguments
-
typedef void (*
wl_log_func_t
)(const char *, va_list) Log function type alias.
The C implementation of the Wayland protocol abstracts the details of logging. Users may customize the logging behavior, with a function conforming to the
wl_log_func_t
type, viawl_log_set_handler_client
andwl_log_set_handler_server
.A
wl_log_func_t
must conform to the expectations ofvprintf
, and expects two arguments: a string to write and a corresponding variable argument list. While the string to write may contain format specifiers and use values in the variable argument list, the behavior of anywl_log_func_t
depends on the implementation.- Note
- Take care to not confuse this with
wl_protocol_logger_func_t
, which is a specific server-side logger for requests and events. - See
- wl_log_set_handler_client
- See
- wl_log_set_handler_server
- Parameters
const char *
: String to write to the log, containing optional format specifiersva_list
: Variable argument list
Enums
-
enum
wl_iterator_result
Return value of an iterator function.
Values:
-
WL_ITERATOR_STOP
Stop the iteration.
-
WL_ITERATOR_CONTINUE
Continue the iteration.
-
Functions
-
static double
wl_fixed_to_double
(wl_fixed_t f) Converts a fixed-point number to a floating-point number.
- Return
- Floating-point representation of the fixed-point argument
- Parameters
f
: Fixed-point number to convert
-
static wl_fixed_t
wl_fixed_from_double
(double d) Converts a floating-point number to a fixed-point number.
- Return
- Fixed-point representation of the floating-point argument
- Parameters
d
: Floating-point number to convert
-
static int
wl_fixed_to_int
(wl_fixed_t f) Converts a fixed-point number to an integer.
- Return
- Integer component of the fixed-point argument
- Parameters
f
: Fixed-point number to convert
-
static wl_fixed_t
wl_fixed_from_int
(int i) Converts an integer to a fixed-point number.
- Return
- Fixed-point representation of the integer argument
- Parameters
i
: Integer to convert
-
-
dir
/home/mvlad/src/wayland/src