JsonrpcClient

JsonrpcClient — a client for JSON-RPC communication

Functions

Properties

GIOStream * io-stream Write / Construct Only
gboolean use-gvariant Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── JsonrpcClient

Description

The JsonrpcClient class provides a convenient API to coordinate with a JSON-RPC server. You can provide the underlying GIOStream to communicate with allowing you to control the negotiation of how you setup your communications channel. One such method might be to use a GSubprocess and communicate over stdin and stdout.

Because JSON-RPC allows for out-of-band notifications from the server to the client, it is important that the consumer of this API calls jsonrpc_client_close() or jsonrpc_client_close_async() when they no longer need the client. This is because JsonrpcClient contains an asynchronous read-loop to process incoming messages. Until jsonrpc_client_close() or jsonrpc_client_close_async() have been called, this read loop will prevent the object from finalizing (being freed).

To make an RPC call, use jsonrpc_client_call() or jsonrpc_client_call_async() and provide the method name and the parameters as a GVariant for call.

It is a programming error to mix synchronous and asynchronous API calls of the JsonrpcClient class.

For synchronous calls, JsonrpcClient will use the thread-default GMainContext. If you have special needs here ensure you've set the context before calling into any JsonrpcClient API.

Functions

jsonrpc_client_error_quark ()

GQuark
jsonrpc_client_error_quark (void);

jsonrpc_client_new ()

JsonrpcClient *
jsonrpc_client_new (GIOStream *io_stream);

Creates a new JsonrpcClient instance.

If you want to communicate with a process using stdin/stdout, consider using GSubprocess to launch the process and create a GSimpleIOStream using the g_subprocess_get_stdin_pipe() and g_subprocess_get_stdout_pipe().

Parameters

io_stream

A GIOStream.

[not nullable]

Returns

A newly created JsonrpcClient.

[transfer full]

Since: 3.26

jsonrpc_client_get_use_gvariant ()

gboolean
jsonrpc_client_get_use_gvariant (JsonrpcClient *self);

Gets the “use-gvariant” property.

Indicates if GVariant is being used to communicate with the peer.

Parameters

self

a JsonrpcClient

 

Returns

TRUE if GVariant is being used; otherwise FALSE.

Since: 3.26

jsonrpc_client_set_use_gvariant ()

void
jsonrpc_client_set_use_gvariant (JsonrpcClient *self,
                                 gboolean use_gvariant);

Sets the “use-gvariant” property.

This function sets if GVariant should be used to communicate with the peer. Doing so can allow for more efficient communication by avoiding expensive parsing overhead and memory allocations. However, it requires that the peer also supports GVariant encoding.

Parameters

self

a JsonrpcClient

 

use_gvariant

if GVariant should be used

 

Since: 3.26

jsonrpc_client_close ()

gboolean
jsonrpc_client_close (JsonrpcClient *self,
                      GCancellable *cancellable,
                      GError **error);

Closes the underlying streams and cancels any inflight operations of the JsonrpcClient. This is important to call when you are done with the client so that any outstanding operations that have caused self to hold additional references are cancelled.

Failure to call this method results in a leak of JsonrpcClient.

Parameters

self

A JsonrpcClient

 

Returns

TRUE if successful; otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_close_async ()

void
jsonrpc_client_close_async (JsonrpcClient *self,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronous version of jsonrpc_client_close()

Currently this operation is implemented synchronously, but in the future may be converted to using asynchronous operations.

Parameters

self

A JsonrpcClient.

 

Since: 3.26

jsonrpc_client_close_finish ()

gboolean
jsonrpc_client_close_finish (JsonrpcClient *self,
                             GAsyncResult *result,
                             GError **error);

Completes an asynchronous request of jsonrpc_client_close_async().

Returns

TRUE if successful; otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_call ()

gboolean
jsonrpc_client_call (JsonrpcClient *self,
                     const gchar *method,
                     GVariant *params,
                     GCancellable *cancellable,
                     GVariant **return_value,
                     GError **error);

Synchronously calls method with params on the remote peer.

once a reply has been received, or failure, this function will return. If successful, return_value will be set with the reslut field of the response.

If params is floating then this function consumes the reference.

Parameters

self

A JsonrpcClient

 

method

the name of the method to call

 

params

A GVariant of parameters or NULL.

[transfer none][nullable]

cancellable

A GCancellable or NULL.

[nullable]

return_value

A location for a JsonNode.

[nullable][out]

Returns

TRUE on success; otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_call_async ()

void
jsonrpc_client_call_async (JsonrpcClient *self,
                           const gchar *method,
                           GVariant *params,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Asynchronously calls method with params on the remote peer.

Upon completion or failure, callback is executed and it should call jsonrpc_client_call_finish() to complete the request and release any memory held.

If params is floating, the floating reference is consumed.

Parameters

self

A JsonrpcClient

 

method

the name of the method to call

 

params

A JsonNode of parameters or NULL.

[transfer none][nullable]

cancellable

A GCancellable or NULL.

[nullable]

callback

a callback to executed upon completion

 

user_data

user data for callback

 

Since: 3.26

jsonrpc_client_call_finish ()

gboolean
jsonrpc_client_call_finish (JsonrpcClient *self,
                            GAsyncResult *result,
                            GVariant **return_value,
                            GError **error);

Completes an asynchronous call to jsonrpc_client_call_async().

Parameters

self

A JsonrpcClient.

 

result

A GAsyncResult provided to the callback in jsonrpc_client_call_async()

 

return_value

A location for a JsonNode or NULL.

[out][nullable]

error

a location for a GError or NULL

 

Returns

TRUE if successful and return_value is set, otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_send_notification ()

gboolean
jsonrpc_client_send_notification (JsonrpcClient *self,
                                  const gchar *method,
                                  GVariant *params,
                                  GCancellable *cancellable,
                                  GError **error);

Synchronously calls method with params on the remote peer. This function will not wait or expect a reply from the peer.

If params is floating then the reference is consumed.

Parameters

self

A JsonrpcClient

 

method

the name of the method to call

 

params

A GVariant of parameters or NULL.

[transfer none][nullable]

cancellable

A GCancellable or NULL.

[nullable]

Returns

TRUE on success; otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_send_notification_async ()

void
jsonrpc_client_send_notification_async
                               (JsonrpcClient *self,
                                const gchar *method,
                                GVariant *params,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously calls method with params on the remote peer. This function will not wait or expect a reply from the peer.

This function is useful when the caller wants to be notified that the bytes have been delivered to the underlying stream. This does not indicate that the peer has received them.

If params is floating then the reference is consumed.

Parameters

self

A JsonrpcClient

 

method

the name of the method to call

 

params

A GVariant of parameters or NULL.

[transfer none][nullable]

cancellable

A GCancellable or NULL.

[nullable]

Since: 3.26

jsonrpc_client_send_notification_finish ()

gboolean
jsonrpc_client_send_notification_finish
                               (JsonrpcClient *self,
                                GAsyncResult *result,
                                GError **error);

Completes an asynchronous call to jsonrpc_client_send_notification_async().

Successful completion of this function only indicates that the request has been written to the underlying buffer, not that the peer has received the notification.

Parameters

self

A JsonrpcClient

 

Returns

TRUE if the bytes have been flushed to the GIOStream; otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_reply ()

gboolean
jsonrpc_client_reply (JsonrpcClient *self,
                      GVariant *id,
                      GVariant *result,
                      GCancellable *cancellable,
                      GError **error);

Synchronous variant of jsonrpc_client_reply_async().

If id or result are floating, there floating references are consumed.

Parameters

self

a JsonrpcClient

 

id

the id of the message to reply result: (transfer none) (nullable): the return value or NULL.

[transfer none][not nullable]

cancellable

a GCancellable, or NULL.

[nullable]

error

a GError, or NULL

 

Since: 3.26

jsonrpc_client_reply_async ()

void
jsonrpc_client_reply_async (JsonrpcClient *self,
                            GVariant *id,
                            GVariant *result,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

jsonrpc_client_reply_finish ()

gboolean
jsonrpc_client_reply_finish (JsonrpcClient *self,
                             GAsyncResult *result,
                             GError **error);

Completes an asynchronous request to jsonrpc_client_reply_async().

Parameters

self

a JsonrpcClient

 

result

A GAsyncResult

 

error

a location for a GError or NULL

 

Returns

TRUE if successful; otherwise FALSE and error is set.

Since: 3.26

jsonrpc_client_reply_error_async ()

void
jsonrpc_client_reply_error_async (JsonrpcClient *self,
                                  GVariant *id,
                                  gint code,
                                  const gchar *message,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously replies to the peer, sending a JSON-RPC error message.

Call jsonrpc_client_reply_error_finish() to get the result of this operation.

If id is floating, it's floating reference is consumed.

Parameters

self

a JsonrpcClient

 

id

a GVariant containing the call id.

[transfer none]

code

the error code

 

message

an optional error message.

[nullable]

cancellable

a GCancellable, or NULL.

[nullable]

callback

a GAsyncReadyCallback or NULL.

[nullable]

user_data

closure data for callback

 

Since: 3.28

jsonrpc_client_reply_error_finish ()

gboolean
jsonrpc_client_reply_error_finish (JsonrpcClient *self,
                                   GAsyncResult *result,
                                   GError **error);

jsonrpc_client_start_listening ()

void
jsonrpc_client_start_listening (JsonrpcClient *self);

This function requests that client start processing incoming messages from the peer.

Parameters

self

a JsonrpcClient

 

Since: 3.26

Types and Values

JSONRPC_TYPE_CLIENT

#define JSONRPC_TYPE_CLIENT  (jsonrpc_client_get_type())

JSONRPC_CLIENT_ERROR

#define JSONRPC_CLIENT_ERROR (jsonrpc_client_error_quark())

enum JsonrpcClientError

Members

JSONRPC_CLIENT_ERROR_PARSE_ERROR

   

JSONRPC_CLIENT_ERROR_INVALID_REQUEST

   

JSONRPC_CLIENT_ERROR_METHOD_NOT_FOUND

   

JSONRPC_CLIENT_ERROR_INVALID_PARAMS

   

JSONRPC_CLIENT_ERROR_INTERNAL_ERROR

   

struct JsonrpcClientClass

struct JsonrpcClientClass {
  GObjectClass parent_class;

  void     (*notification) (JsonrpcClient *self,
                            const gchar   *method_name,
                            GVariant      *params);
  gboolean (*handle_call)  (JsonrpcClient *self,
                            const gchar   *method,
                            GVariant      *id,
                            GVariant      *params);
  void     (*failed)       (JsonrpcClient *self);

  gpointer _reserved2;
  gpointer _reserved3;
  gpointer _reserved4;
  gpointer _reserved5;
  gpointer _reserved6;
  gpointer _reserved7;
  gpointer _reserved8;
};

JsonrpcClient

typedef struct _JsonrpcClient JsonrpcClient;

Property Details

The “io-stream” property

  “io-stream”                GIOStream *

The "io-stream" property is the GIOStream to use for communicating with a JSON-RPC peer.

Flags: Write / Construct Only

Since: 3.26

The “use-gvariant” property

  “use-gvariant”             gboolean

The "use-gvariant" property denotes if GVariant should be used to communicate with the peer instead of JSON. You should only set this if you know the peer is also a Jsonrpc-GLib based client.

Setting this property allows the peers to communicate using GVariant instead of JSON. This means that we can access the messages without expensive memory allocations and parsing costs associated with JSON. GVariant is much more optimal for memory-bassed message passing.

Flags: Read / Write

Default value: FALSE

Since: 3.26

Signal Details

The “failed” signal

void
user_function (JsonrpcClient *jsonrpcclient,
               gpointer       user_data)

The "failed" signal is called when the client has failed communication or the connection has been knowingly closed.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 3.28

The “handle-call” signal

gboolean
user_function (JsonrpcClient *self,
               gchar         *method,
               GVariant      *id,
               GVariant      *params,
               gpointer       user_data)

This signal is emitted when an RPC has been received from the peer we are connected to. Return TRUE if you have handled this message, even asynchronously. If no handler has returned TRUE an error will be synthesized.

If you handle the message, you are responsible for replying to the peer in a timely manner using jsonrpc_client_reply() or jsonrpc_client_reply_async().

Additionally, since 3.28 you may connect to the "detail" of this signal to handle a specific method call. Use the method name as the detail of the signal.

Parameters

self

A JsonrpcClient

 

method

the method name.

[not nullable]

id

The "id" field of the JSONRPC message.

[not nullable]

params

The "params" field of the JSONRPC message.

[nullable]

user_data

user data set when the signal handler was connected.

 

Flags: Has Details

Since: 3.26

The “notification” signal

void
user_function (JsonrpcClient *self,
               gchar         *method,
               GVariant      *params,
               gpointer       user_data)

This signal is emitted when a notification has been received from a peer. Unlike “handle-call”, this does not have an "id" parameter because notifications do not have ids. They do not round trip.

Parameters

self

A JsonrpcClient

 

method

the method name of the notification

 

params

params for the notification.

[nullable]

user_data

user data set when the signal handler was connected.

 

Flags: Has Details

Since: 3.26