Function scan can be used to retrieve parameters from the parameter set. The function accepts variable number of parameters. The first parameter is the formatting string that determines the type of the parameters to be retrieved. Each parameter is represented by exactly one parameter type character in the string. The variable part of parameters must contain as many pointers to C variables as there are formatting non-modifiers characters in the formatting string.

Besides characters representing parameter types, the formatting string can contain two special modifiers: "*" and ".". The modifiers do not have a correspondent in the variable part of the parameters.

The meaning of "*" modifier is that any further parameters (defined by other type characters in the formatting string) are optional (they can be missing in the input and no rpc fault will automatically be generated).

The '.' modifiers turns on type autoconversion for the next parameter. This means that if the type of the next parameter differs from the type specified in the formatting string, the parameter will be automatically converted to the formatting string type (if possible) and if the automatic conversion succeeds, no fault will be generated.

The function returns the number of parameters read on success (a number greater or equal 0) and - (minus) the number of parameters read on error (for example for an error after reading 2 parameters it will return -2). When a failure occurs (incorrect parameter type or no more parameters in the parameter set) the function will return a negative number (- number of parameters read so far) and it will also automatically change the reply that will be sent to the caller to indicate that a failure has occurred on the server (unless the "*" is used and the error is lack of more parameters).

The prototype of the function is:

int scan((void* ctx, char* fmt, ...)

It is possible to either call the function once to scan all the parameters:

rpc->scan(ctx, "sdf", &string_val, &int_val, &double_val);

Or you can call the same function several times and it will continue where it left off previously:

rpc->scan(ctx, "s", &string_val);
rpc->scan(ctx, "d", &int_val);
rpc->scan(ctx, "f", &double_val);

Function struct_scan can be used to retrieve named attributes from a parameter of type structure.

When retrieving a structure parameter from the parameter set:

rpc->scan(ctx, "{", &handle);

The corresponding variable (named handle in the example above) will contain the index of the structure parameter within the parameter set, but the index cannot be used to retrieve the contents of the structure. To retrieve the contents of the structure you can use function struct_scan. The function gets the handle as the first parameter:

rpc->struct_scan(handle, "sd", "str_attr", &str_val, "int_attr", &int_val);

The second parameter is the formatting string followed by pairs of parameters. First parameter in each pair is the name of the attribute to retrieve (string) and the second parameter in each pair is the pointer to the variable to store the value of the parameter. The function returns the number of parameters (name value pairs) read on success and - number of parameters read so far on an error (just like the scan function). The function also indicates an error if a requested attribute is missing in the structure.

You can use fault function to indicate that an error has occurred on the server to the caller. The function accepts two parameters. The first parameter is the status code and the second parameter is the reason phrase.

static void rpc_my_function(rpc_t* rpc, void *ctx)
{
    rpc->fault(ctx, 600, "Not Yet Implemented");
}

If your function first creates some result using add, or printf functions then all the data will be lost once you call fault function. Failure replies must not contain any data:

static void rpc_my_function(rpc_t* rpc, void *ctx)
{
    rpc->add(ctx, "s", "result1");
    rpc->add(ctx, "d", variable);

    /* Reply created by previous functions will be
     * deleted and a failure reply 600 Not Yet Implemented
     * will be created instead
     */
    rpc->fault(ctx, 600, "Not Yet Implemented");

    /* You can also add data here, but that will have no
     * effect
     */
    rpc->add(ctx, "s", "result2");
}

Similarly you can also call add or printf functions after calling fault, in this case they will have no effect:

static void rpc_my_function(rpc_t* rpc, void *ctx)
{
    rpc->fault(ctx, 600, "Not Yet Implemented");

    /* You can also add data here, but that will have no
     * effect and only 600 Not Yet Implemented will be returned
     */
    rpc->add(ctx, "s", "result2");
}

RPC functions can use function send to explicitly send the reply. Each RPC function call generates exactly one reply. No reply will be sent after the function finishes if it already sent the reply using send function explicitly. This function is especially useful if the RPC function needs to perform some (potentially destructive) actions after the reply has been sent.

static void core_kill(rpc_t* rpc, void *ctx)
{
    int sig_no;

    if (rpc->scan(ctx, "d", &sig_no) < 0) return;
    rpc->send(ctx, );     /* First send a reply */
    kill(0, sig_no); /* Then kill the server */
}

Function add can be used to add arbitrary data to the result set. Its parameters and use are analogical to scan function described in Section 1.2.3.1, “scan”. The first parameter of the function is the formatting string that determines the types of additional parameters:

static void rpc_func(rpc_t* rpc, void *ctx)
{
    str str_result;
    int int_result;
    void *handle;
    double float_result;

    if (rpc->add(ctx, "Sdf{", &str_result, int_result, float_result, &handle) < 0) return;
}

Naturally you can call this function several times, adding only one piece of data at a time. The function returns 0 on success and -1 on an error. In case of an error the reply is set automatically with corresponding error code and reason phrase.

The last character in the formatting string of the function above indicates that the last data to be added will be a structure. This deserves some clarification. In this case, the function will create an empty structure and the handle to the newly created structure will be stored in handle variable (hence the last parameter is pointer to an integer). In this particular example parameters str_result, int_result, and float_result will be used for reading while parameter handle will be used for writing by the function.

You can set the attributes of the newly created structure using struct_add function described in Section 1.2.4.5, “struct_add”.

printf is a convenience function. The function adds data of type string to the result set. The first parameter of the function is again a formatting string, but this time it is printf-like formatting string:

if (rpc->printf(ctx, "Unable to delete %d entries from table %s", num_entries, table_name) < 0) return;

The return value of the function is the same as of add function.

Function struct_add can be used to add attributes to a structure (created previously by add function). The first parameter of the function is handle obtained through add function, the second parameters is formatting string that determines the types of attributes to be added. There must be two parameters per each character in the formatting string, the first one is the name of the attribute, the second parameter is the value of the attribute. If a parameter with such a name already exist in the structure then it will be overwritten with the new value.

static void rpc_func(rpc_t* rpc, void *ctx)
{
    void *handle;

        /* Create empty structure and obtain its handle */
    if (rpc->add(ctx, "{", &handle) < 0) return;
        /* Fill-in the structure */
    if (rpc->struct_add(handle, "sd", "attr1", str_val,
                                      "attr2", int_val ) < 0)
        return;
}

The function returns -1 on an error (and sets the status code and reason phrase of the reply accordingly) and 0 on success.