![]() |
![]() |
![]() |
![]() |
#define | JSONRPC_TYPE_CLIENT |
#define | JSONRPC_CLIENT_ERROR |
enum | JsonrpcClientError |
struct | JsonrpcClientClass |
JsonrpcClient |
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.
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()
.
Since: 3.26
gboolean
jsonrpc_client_get_use_gvariant (JsonrpcClient *self
);
Gets the “use-gvariant” property.
Indicates if GVariant is being used to communicate with the peer.
Since: 3.26
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.
Since: 3.26
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.
Since: 3.26
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.
Since: 3.26
gboolean jsonrpc_client_close_finish (JsonrpcClient *self
,GAsyncResult *result
,GError **error
);
Completes an asynchronous request of jsonrpc_client_close_async()
.
Since: 3.26
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.
self |
||
method |
the name of the method to call |
|
params |
[transfer none][nullable] | |
cancellable |
A GCancellable or |
[nullable] |
return_value |
A location for a JsonNode. |
[nullable][out] |
Since: 3.26
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.
self |
||
method |
the name of the method to call |
|
params |
[transfer none][nullable] | |
cancellable |
A GCancellable or |
[nullable] |
callback |
a callback to executed upon completion |
|
user_data |
user data for |
Since: 3.26
gboolean jsonrpc_client_call_finish (JsonrpcClient *self
,GAsyncResult *result
,GVariant **return_value
,GError **error
);
Completes an asynchronous call to jsonrpc_client_call_async()
.
self |
||
result |
A GAsyncResult provided to the callback in |
|
return_value |
[out][nullable] | |
error |
Since: 3.26
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.
self |
||
method |
the name of the method to call |
|
params |
[transfer none][nullable] | |
cancellable |
A GCancellable or |
[nullable] |
Since: 3.26
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.
self |
||
method |
the name of the method to call |
|
params |
[transfer none][nullable] | |
cancellable |
A GCancellable or |
[nullable] |
Since: 3.26
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.
Since: 3.26
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.
self |
||
id |
the id of the message to reply
result: (transfer none) (nullable): the return value or |
[transfer none][not nullable] |
cancellable |
a GCancellable, or |
[nullable] |
error |
Since: 3.26
void jsonrpc_client_reply_async (JsonrpcClient *self
,GVariant *id
,GVariant *result
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
gboolean jsonrpc_client_reply_finish (JsonrpcClient *self
,GAsyncResult *result
,GError **error
);
Completes an asynchronous request to jsonrpc_client_reply_async()
.
Since: 3.26
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.
self |
||
id |
a GVariant containing the call id. |
[transfer none] |
code |
the error code |
|
message |
an optional error message. |
[nullable] |
cancellable |
a GCancellable, or |
[nullable] |
callback |
a GAsyncReadyCallback or |
[nullable] |
user_data |
closure data for |
Since: 3.28
gboolean jsonrpc_client_reply_error_finish (JsonrpcClient *self
,GAsyncResult *result
,GError **error
);
void
jsonrpc_client_start_listening (JsonrpcClient *self
);
This function requests that client start processing incoming messages from the peer.
Since: 3.26
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; };
“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
“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
“failed”
signalvoid 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.
Flags: Run Last
Since: 3.28
“handle-call”
signalgboolean 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.
self |
||
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
“notification”
signalvoid 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.
self |
||
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