scapi.h

/*
 * Copyright (C) 2016 prpl Foundation
 * Written by Felix Fietkau <nbd@nbd.name>
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
#ifndef __SCAPI_H
#define __SCAPI_H

#include <libubox/blobmsg.h>
#include <libubox/list.h>
#include <libubox/kvlist.h>
#include <stdbool.h>

struct scapi_model;
struct scapi_object;
struct scapi_parameter;
struct scapi_list_ctx;

typedef void (*scapi_object_cb)(struct scapi_list_ctx *ctx,
				struct scapi_object *obj);

typedef void (*scapi_param_cb)(struct scapi_list_ctx *ctx,
				struct scapi_parameter *par);

struct scapi_ptr {
	struct scapi_plugin *plugin;
	struct scapi_model *model;
	void *model_priv;

	struct blob_attr *path;
	struct scapi_object *obj;
	struct scapi_parameter *par;

	struct blob_attr *value;
};

struct scapi_plugin {
	const char *name;

	/*
	 * Free plugin (unused right now)
	 */
	void (*free)(void);

	/*
	 * Free model (unused right now)
	 */
	void (*model_free)(struct scapi_model *model, void *priv);

	/*
	 * Fetch a list of child objects by path
	 *
	 * ptr: reference to plugin, data model and the path
	 * fill: callback for passing objects to the caller
	 * ctx: opaque data structure used by scald, passed to fill()
	 *
	 * Lifetime of struct scapi_object items is controlled by
	 * the plugin and needs to be guaranteed only until the end
	 * of the object_list call.
	 * The plugin may re-use and overwrite the data from the
	 * previous fill call
	 */
	int (*object_list)(struct scapi_ptr *ptr, scapi_object_cb fill,
			   struct scapi_list_ctx *ctx);

	/* 
	 * Fetch a reference to an object by path
	 *
	 * ptr: reference to plugin, data model and the path
	 *
	 * The pointer to the object is stored inside ptr
	 *
	 * Lifetime of the object is controlled by the plugin and
	 * must be guaranteed until the next call to object_get,
	 * object_list or free, or until the object is deleted
	 */
	int (*object_get)(struct scapi_ptr *ptr);

	/*
	 * Create a new object instance
	 *
	 * ptr: reference to plugin, data model, path to the parent object
	 * name: name of the new object instance
	 *
	 * Must return SC_ERR_NOT_SUPPORTED if the plugin does not support creating
	 * an object on the specified path and another plugin might.
	 *
	 * All other errors are treated as fatal and do not allow deferring to a
	 * different plugin.
	 */
	int (*object_add)(struct scapi_ptr *ptr, const char *name);

	/*
	 * Delete an object instance
	 *
	 * ptr: reference to plugin, data model and object
	 *      (provided by .object_list or .object_get)
	 */
	int (*object_remove)(struct scapi_ptr *ptr);

	/*
	 * Fetch extra object attributes to pass to the ACL check daemon
	 *
	 * ptr: reference to plugin, data model and object
	 *      (provided by .object_list or .object_get)
	 * buf: blob_buf to store the values.
	 */
	void (*object_get_acl)(struct scapi_ptr *ptr, struct blob_buf *buf);

	/*
	 * List parameters belonging to an object
	 *
	 * ptr: reference to plugin, data model and object
	 *      (provided by .object_list or .object_get)
	 * fill: callback for passing paramters to the caller
	 * ctx: opaque data structure used by scald, passed to fill()
	 *
	 * Lifetime of struct scapi_parameter items is controlled by
	 * the plugin and needs to be guaranteed only until the end
	 * of the param_list call.
	 * The plugin may re-use and overwrite the data from the
	 * previous fill call
	 */
	int (*param_list)(struct scapi_ptr *ptr, scapi_param_cb fill,
			  struct scapi_list_ctx *ctx);

	/*
	 * Get a parameter belonging to an object
	 *
	 * ptr: reference to plugin, data model and object
	 *      (provided by .object_list or .object_get)
	 * name: name of the parameter
	 * par: destination for storing the parameter reference
	 *
	 * The pointer to the parameter is stored inside ptr
	 *
	 * Lifetime of the parameter is controlled by the plugin and
	 * must be guaranteed until the next call to param_get,
	 * param_list or free
	 */
	int (*param_get)(struct scapi_ptr *ptr, const char *name);

	/*
	 * Fetch extra parameter attributes to pass to the ACL check daemon
	 *
	 * ptr: reference to plugin, data model, object
	 *      (provided by .object_list or .object_get) and parameter
	 *      (provided by .param_list or .param_get)
	 * buf: blob_buf to store the values.
	 */
	void (*param_get_acl)(struct scapi_ptr *ptr, struct blob_buf *buf);

	/*
	 * Get a parameter value
	 *
	 * ptr: reference to plugin, data model, object
	 *      (provided by .object_list or .object_get) and parameter
	 *      (provided by .param_list or .param_get)
	 * buf: blob_buf to store the value.
	 *
	 * When the storing the value inside the blob_buf,
	 * it must be named 'value'
	 */
	int (*param_read)(struct scapi_ptr *ptr, struct blob_buf *buf);

	/*
	 * Set a parameter value
	 *
	 * ptr: reference to plugin, data model, object
	 *      (provided by .object_list or .object_get) and parameter
	 *      (provided by .param_list or .param_get)
	 * val: new value
	 */
	int (*param_write)(struct scapi_ptr *ptr, struct blob_attr *val);

	/*
	 * Validate all changes (optional)
	 * If your plugin doesn't have a validation mechanism, this isn't needed.
	 *
	 * ptr: reference to plugin, data model
	 */
	int (*validate)(struct scapi_ptr *ptr);

	/*
	 * Commit all changes (optional)
	 * If your plugin directly modifies data without a commit stage,
	 * this isn't needed
	 *
	 *
	 * ptr: reference to plugin, data model
	 */
	int (*commit)(struct scapi_ptr *ptr);
};

struct scapi_model {
	const char *name;
};

struct scapi_object {
	const char *name;
	bool multi_instance;
};

struct scapi_parameter {
	const char *name;
	bool readonly;
};

enum scald_log_level {
	SCAPI_LOG_ERROR,
	SCAPI_LOG_WARNING,
	SCAPI_LOG_INFO,
	SCAPI_LOG_DEBUG,
};

enum scapi_error {
	SC_ERR_UNKNOWN = 1,
	SC_ERR_INVALID_ARGUMENT,
	SC_ERR_NOT_FOUND,
	SC_ERR_NOT_SUPPORTED,
	SC_ERR_INVALID_DATA,
	SC_ERR_NO_DATA,
	SC_ERR_UPDATE_FAILED,
	SC_ERR_ACCESS_DENIED,
	SC_ERR_ALREADY_EXISTS,
	__SC_ERR_MAX,
};

/* scald callbacks that can be called from scapi plugins */
struct scapi_cb {
	/*
	 * Initialize a plugin
	 * Called inside the plugin to register itself with scald
	 *
	 * p: pointer to plugin being registered to scald
	 */
	void (*plugin_add) (struct scapi_plugin *p);

	/*
	 * Add a new data model (or return an existing one with the same name)
	 *
	 * p: pointer to the plugin registering the data model
	 * name: name of the data model
	 * priv: pointer to an internal plugin. Example: a JSON plugin defined
	 *       in JSON file would be in p but the overall JSON plugin goes in priv
	 */
	struct scapi_model *(*model_add)(struct scapi_plugin *p, const char *name, void *priv);

	/* Get an scald command line option specified via -x */
	const char *(*option_get)(const char *name);

	/* Log a message from the plugin up to scald */
	void (*log_msg)(struct scapi_plugin *p, enum scald_log_level level, const char *fmt, ...);
};

/* Defined by scapi plugin */
void scapi_module_init(const struct scapi_cb *cb);

#endif