flux_respond(3)

SYNOPSIS

#include <flux/core.h>

int flux_respond (flux_t *h,
                  const flux_msg_t *request,
                  const char *s);

int flux_respond_pack (flux_t *h,
                       const flux_msg_t *request,
                       const char *fmt,
                       ...);

int flux_respond_raw (flux_t *h,
                      const flux_msg_t *request,
                      const void *data,
                      int length);

int flux_respond_error (flux_t *h,
                        const flux_msg_t *request,
                        int errnum,
                        const char *errmsg);

Link with -lflux-core.

DESCRIPTION

flux_respond(), flux_respond_pack(), flux_respond_raw(), and flux_respond_error() encode and send a response message on handle h, deriving topic string, matchtag, and route stack from the provided request.

flux_respond() sends a response to request. If s is non-NULL, flux_respond() will send it as the response payload, otherwise there will be no payload.

flux_respond_raw() is identical except if data is non-NULL, flux_respond_raw() will send it as the response payload.

flux_respond_pack() encodes a response message with a JSON payload, building the payload using variable arguments with a format string in the style of jansson's json_pack() (used internally).

flux_respond_error() returns an error response to the sender. If errnum is zero, EINVAL is used. If errmsg is non-NULL, an error string payload is included in the response. The error string may be used to provide a more detailed error message than can be conveyed via errnum.

STREAMING SERVICES

Per RFC 6, a "streaming" service must return zero or more non-error responses to a request and a final error response. If the requested operation was successful, the final error response may use ENODATA as the error number. Clients should interpret ENODATA as a non-error end-of-stream marker.

It is essential that services which return multiple responses verify that requests were made with the FLUX_RPC_STREAMING flag by testing the FLUX_MSGFLAG_STREAMING flag, e.g. using flux_msg_is_streaming(3). If the flag is not set, the service must return an immediate EPROTO error.

ENCODING JSON PAYLOADS

Flux API functions that are based on Jansson's json_pack() accept the following tokens in their format string. The type in parenthesis denotes the resulting JSON type, and the type in brackets (if any) denotes the C type that is expected as the corresponding argument or arguments.

s (string)['const char *']

Convert a null terminated UTF-8 string to a JSON string.

s? (string)['const char *']

Like s, but if the argument is NULL, outputs a JSON null value.

s# (string)['const char *', 'int']

Convert a UTF-8 buffer of a given length to a JSON string.

s% (string)['const char *', 'size_t']

Like s# but the length argument is of type size_t.

+ ['const char *']

Like s, but concatenate to the previous string. Only valid after a string.

+# ['const char *', 'int']

Like s#, but concatenate to the previous string. Only valid after a string.

+% ['const char *', 'size_t']

Like +#, but the length argument is of type size_t.

n (null)

Output a JSON null value. No argument is consumed.

b (boolean)['int']

Convert a C int to JSON boolean value. Zero is converted to false and non-zero to true.

i (integer)['int']

Convert a C int to JSON integer.

I (integer)['int64_t']

Convert a C int64_t to JSON integer. Note: Jansson expects a json_int_t here without committing to a size, but Flux guarantees that this is a 64-bit integer.

f (real)['double']

Convert a C double to JSON real.

o (any value)['json_t *']

Output any given JSON value as-is. If the value is added to an array or object, the reference to the value passed to o is stolen by the container.

O (any value)['json_t *']

Like o, but the argument's reference count is incremented. This is useful if you pack into an array or object and want to keep the reference for the JSON value consumed by O to yourself.

o?, O? (any value)['json_t *']

Like o and O, respectively, but if the argument is NULL, output a JSON null value.

[fmt] (array)

Build an array with contents from the inner format string. fmt may contain objects and arrays, i.e. recursive value building is supported.

{fmt} (object)

Build an object with contents from the inner format string fmt. The first, third, etc. format specifier represent a key, and must be a string as object keys are always strings. The second, fourth, etc. format specifier represent a value. Any value may be an object or array, i.e. recursive value building is supported.

Whitespace, : (colon) and , (comma) are ignored.

These descriptions came from the Jansson 2.9 manual.

See also: Jansson API: Building Values: http://jansson.readthedocs.io/en/2.9/apiref.html#building-values

RETURN VALUE

These functions return zero on success. On error, -1 is returned, and errno is set appropriately.

ERRORS

ENOSYS

Handle has no send operation.

EINVAL

Some arguments were invalid.

EPROTO

A protocol error was encountered.

RESOURCES

Flux: http://flux-framework.org

Flux RFC: https://flux-framework.readthedocs.io/projects/flux-rfc

FLUX_RFC

6/Flux Remote Procedure Call Protocol

3/Flux Message Protocol

SEE ALSO

flux_rpc(3), flux_rpc_raw(3)