JsonrpcClient: Jsonrpc-GLib Reference Manual

## JsonrpcClient JsonrpcClient — a client for JSON-RPC communication |

## Functions

GQuark | jsonrpc_client_error_quark ()
JsonrpcClient * | jsonrpc_client_new ()
gboolean | jsonrpc_client_get_use_gvariant ()
void | jsonrpc_client_set_use_gvariant ()
gboolean | jsonrpc_client_close ()
void | jsonrpc_client_close_async ()
gboolean | jsonrpc_client_close_finish ()
gboolean | jsonrpc_client_call ()
void | jsonrpc_client_call_with_id_async ()
void | jsonrpc_client_call_async ()
gboolean | jsonrpc_client_call_finish ()
gboolean | jsonrpc_client_send_notification ()
void | jsonrpc_client_send_notification_async ()
gboolean | jsonrpc_client_send_notification_finish ()
gboolean | jsonrpc_client_reply ()
void | jsonrpc_client_reply_async ()
gboolean | jsonrpc_client_reply_finish ()
void | jsonrpc_client_reply_error_async ()
gboolean | jsonrpc_client_reply_error_finish ()
void | jsonrpc_client_start_listening ()

## Properties

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

## Signals

void | failed | Run Last
gboolean | handle-call | Has Details
void | notification | Has Details

## Types and Values

#define | JSONRPC_TYPE_CLIENT
#define | JSONRPC_CLIENT_ERROR
enum | JsonrpcClientError
struct | JsonrpcClientClass
| JsonrpcClient

## 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 GVariant. | [nullable][out]

#### Returns

`TRUE` on success; otherwise `FALSE` and `error` is set.

Since: 3.26

### jsonrpc_client_call_with_id_async ()

    void
    jsonrpc_client_call_with_id_async (JsonrpcClient *self,
                                       const gchar *method,
                                       GVariant *params,
                                       GVariant **id,
                                       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.

This function is similar to `jsonrpc_client_call_async()` except that it allows the caller to get the id of the command which might be useful in systems where you can cancel the operation (such as the Language Server Protocol).

If `params` is floating, the floating 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]
id | a location for a GVariant describing the identifier used for the method call, or `NULL`. | [out][transfer full][optional]
cancellable | A GCancellable or `NULL`. | [nullable]
callback | a callback to executed upon completion |
user_data | user data for `callback` |

Since: 3.30

### 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 GVariant 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 GVariant 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. | [transfer none][not nullable]
result | the return value or `NULL`. | [transfer none][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.

Owner: JsonrpcClient

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.

Owner: JsonrpcClient

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