sd_varlink_call_and_upgrade

systemd

sd_varlink_call_and_upgradeb

sd_varlink_call_and_upgradebo

sd_varlink_invoke_and_upgrade

sd_varlink_invoke_and_upgradeb

sd_varlink_invoke_and_upgradebo

Invoke a Varlink method and take over the connection for a raw protocol

#include <systemd/sd-varlink.h>

int

sd_varlink_call_and_upgrade

sd_varlink *

link

const char *

method

sd_json_variant *

parameters

sd_json_variant **

ret_parameters

const char **

ret_error_id

int *

ret_input_fd

int *

ret_output_fd

int

sd_varlink_call_and_upgradeb

sd_varlink *

link

const char *

method

sd_json_variant **

ret_parameters

const char **

ret_error_id

int *

ret_input_fd

int *

ret_output_fd

…

int

sd_varlink_call_and_upgradebo

sd_varlink *

link

const char *

method

sd_json_variant **

ret_parameters

const char **

ret_error_id

int *

ret_input_fd

int *

ret_output_fd

…

int

sd_varlink_invoke_and_upgrade

sd_varlink *

link

const char *

method

sd_json_variant *

parameters

int

sd_varlink_invoke_and_upgradeb

sd_varlink *

link

const char *

method

…

int

sd_varlink_invoke_and_upgradebo

sd_varlink *

link

const char *

method

…

Description

These functions implement the client side of a Varlink protocol upgrade. They are the counterpart of the server-side sd_varlink_reply_and_upgrade(3) family. If a method call is issued this way, the connection may switch, after the reply, from the Varlink protocol to an arbitrary, non-Varlink ("raw") protocol spoken over the underlying socket or pipe file descriptors, in a manner similar to the Upgrade: mechanism of HTTP.

sd_varlink_call_and_upgrade() synchronously invokes the method method on the connection link, requesting a protocol upgrade, and waits for the reply. It takes the Varlink connection object, the method name, a JSON object with the method call parameters (which may be NULL), two output pointers for the reply parameters and a possible error identifier, and two output pointers for the file descriptors. The reply parameters returned in ret_parameters and the error identifier returned in ret_error_id are borrowed references that remain valid only until the connection is closed or unreffed. Either of the two may be passed as NULL if the information is not needed.

If the server replies with a regular reply (rather than a Varlink error) the connection is upgraded: it is disconnected from the Varlink protocol, and ownership of the underlying file descriptors is transferred to the caller via ret_input_fd and ret_output_fd, which is responsible for eventually closing them with close(2). If the server replies with a Varlink error instead, the connection is not upgraded and no file descriptors are returned; the error identifier is reported in ret_error_id (if non-NULL), otherwise a negative errno-style error derived from it is returned.

The returned file descriptors are switched to blocking mode. For bidirectional sockets a single underlying file descriptor carries both directions; in this case ret_input_fd and ret_output_fd are returned as two independent (duplicated) descriptors referring to the same socket, so they may be closed separately. For transports backed by a pair of pipes the two descriptors differ and refer to the distinct read and write ends. At least one of ret_input_fd or ret_output_fd must be non-NULL.

sd_varlink_call_and_upgradeb() is similar to sd_varlink_call_and_upgrade(), but instead of expecting a fully constructed sd_json_variant object carrying the method call parameters, this object is constructed on-the-fly from the variadic argument list, in a style identical to sd_json_build(3). sd_varlink_call_and_upgradebo() is identical to sd_varlink_call_and_upgradeb(), but an enclosing JSON object is added implicitly, so that the argument list is expected to consist of object field pairs only, in a style identical to sd_json_buildo(3). This relationship mirrors that of sd_varlink_call(3) and its sd_varlink_callb()/sd_varlink_callbo() variants.

sd_varlink_invoke_and_upgrade() is the asynchronous counterpart of sd_varlink_call_and_upgrade(), for connections attached to an event loop with sd_varlink_attach_event(3). It enqueues the method call with the upgrade request and returns immediately. Once the reply arrives it is passed to the reply callback installed with sd_varlink_bind_reply(3). If the server replied with a Varlink error, the connection stays in the Varlink protocol and may be used further. Otherwise the connection is upgraded on the next dispatch after the reply callback returned (i.e. the next invocation of sd_varlink_process(), typically by the event loop): it is detached from the event loop, disconnected from the Varlink protocol, and the underlying file descriptors are passed to the upgrade callback installed with sd_varlink_bind_upgrade(3), with the same semantics as the descriptors returned by sd_varlink_call_and_upgrade(). The callback takes ownership of both descriptors. Unlike with regular method calls, no further method calls may be enqueued on the connection while an upgrade request is pending, since the connection leaves the Varlink protocol once the request has been answered. sd_varlink_invoke_and_upgradeb() and sd_varlink_invoke_and_upgradebo() relate to sd_varlink_invoke_and_upgrade() like the …b() and …bo() variants described above.

Return Value

On success, sd_varlink_call_and_upgrade() and its variants return a positive integer if the connection was upgraded. If the server returns a Varlink error and ret_error_id was provided by the caller, it is set to the error identifier and zero is returned. Otherwise, the Varlink error is treated as a failure. sd_varlink_invoke_and_upgrade() and its variants return zero once the request has been enqueued. On failure, all functions return a negative errno-style error code.

Errors

Returned errors may indicate the following problems:

-EINVAL
An argument is invalid.

-ENOTCONN
The Varlink connection object is not connected.

-EBUSY
Another method call is pending on the connection. Note that while a request enqueued with sd_varlink_invoke_and_upgrade() is pending, this error is also returned by any other function that enqueues a method call on the connection, such as sd_varlink_call(3) or sd_varlink_invoke().

-EPROTO
A protocol error occurred, for example the server sent unexpected raw protocol data before the upgrade completed.

-ENOMEM
Memory allocation failed.

History

sd_varlink_call_and_upgrade() was added in version 261.

sd_varlink_call_and_upgradeb() and sd_varlink_call_and_upgradebo() were added in version 262.

sd_varlink_invoke_and_upgrade(), sd_varlink_invoke_and_upgradeb() and sd_varlink_invoke_and_upgradebo() were added in version 263.