sd_varlink_call_and_upgrade(3)

.SH "NAME" sd_varlink_call_and_upgrade, sd_varlink_call_and_upgradeb, sd_varlink_call_and_upgradebo - Invoke a Varlink method and take over the connection for a raw protocol

.SH "SYNOPSIS"

#include <systemd/sd-varlink.h>

.HP 768u 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);

.HP 792u 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, ...);

.HP 816u 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, ...);

.SH "DESCRIPTION"

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

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

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

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

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

.SH "RETURN VALUE"

.PP On success, these functions return a positive integer if the connection was upgraded, or zero if the server returned a Varlink error and ret_error_id was set to it. On failure, they return a negative errno-style error code.

.SS "Errors"

.PP Returned errors may indicate the following problems:

.PP -EINVAL