/*

 * Copyright (C) 2017 Red Hat, Inc.

 *

 * This program is free software: you can redistribute it and/or modify

 * it under the terms of the GNU General Public License as published by

 * the Free Software Foundation, either version 3 of the License, or

 * (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program.  If not, see <http://www.gnu.org/licenses/>.

 *

 * Author: Gris Ge <fge@redhat.com>

 */

#ifndef _LIB_OPEN_ISCSI_USR_H_

#define _LIB_OPEN_ISCSI_USR_H_

#ifdef __cplusplus

extern "C" {

#endif

#include <stdint.h>

#include <stdarg.h>

#include <stdbool.h>

#include "libopeniscsiusr_common.h"

#include "libopeniscsiusr_session.h"

#include "libopeniscsiusr_iface.h"

#include "libopeniscsiusr_node.h"

/**

 * iscsi_log_priority_str() - Convert log priority to string.

 *

 * Convert log priority to string (const char *).

 *

 * @priority:

 *	int. Log priority.

 *

 * Return:

 *	const char *. Please don't free returned pointer. Valid string are:

 *

 *	* "ERROR" for LIBISCSI_LOG_PRIORITY_ERROR

 *

 *	* "WARN"  for LIBISCSI_LOG_PRIORITY_WARNING

 *

 *	* "INFO"  for LIBISCSI_LOG_PRIORITY_INFO

 *

 *	* "DEBUG" for LIBISCSI_LOG_PRIORITY_DEBUG

 *

 *	* "Invalid argument" for invalid log priority.

 */

__DLL_EXPORT const char *iscsi_log_priority_str(int priority);

/**

 * iscsi_strerror() - Convert error code to string.

 *

 * Convert error code (int) to string (const char *):

 *

 *	* LIBISCSI_OK -- "OK"

 *

 *	* LIBISCSI_ERR_BUG -- "BUG of libopeniscsiusr library"

 *

 *	* LIBISCSI_ERR_SESS_NOT_FOUND - "Specified iSCSI session not found"

 *

 *	* LIBISCSI_ERR_ACCESS - "Permission deny"

 *

 *	* LIBISCSI_ERR_NOMEM - "Out of memory"

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP - "Could not lookup object in sysfs"

 *

 *	* Other invalid error number -- "Invalid argument"

 *

 * @rc:

 *	int. Return code by libiscsiur functions. When provided error code is

 *	not a valid error code, return "Invalid argument".

 *

 * Return:

 *	const char *. The meaning of provided error code. Don't free returned

 *	pointer.

 */

__DLL_EXPORT const char *iscsi_strerror(int rc);

/**

 * iscsi_context_new() - Create struct iscsi_context.

 *

 * The default logging level (LIBISCSI_LOG_PRIORITY_DEFAULT) is

 * LIBISCSI_LOG_PRIORITY_WARNING which means only warning and error message will

 * be forward to log handler function.  The default log handler function will

 * print log message to STDERR, to change so, please use

 * iscsi_context_log_func_set() to set your own log handler, check manpage

 * libopeniscsiusr.h(3) for detail.

 *

 * Return:

 *	Pointer of 'struct iscsi_context'. Should be freed by

 *	iscsi_context_free().

 */

__DLL_EXPORT struct iscsi_context *iscsi_context_new(void);

/**

 * iscsi_context_free() - Release the memory of struct iscsi_context.

 *

 * Release the memory of struct iscsi_context, but the userdata memory defined

 * via iscsi_context_userdata_set() will not be touched.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_context_free(struct iscsi_context *ctx);

/**

 * iscsi_context_log_priority_set() - Set log priority.

 *

 *

 * When library generates log message, only equal or more important(less value)

 * message will be forwarded to log handler function. Valid log priority values

 * are:

 *

 *	* LIBISCSI_LOG_PRIORITY_ERROR -- 3

 *

 *	* LIBISCSI_LOG_PRIORITY_WARNING -- 4

 *

 *	* LIBISCSI_LOG_PRIORITY_INFO -- 6

 *

 *	* LIBISCSI_LOG_PRIORITY_DEBUG -- 7

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 *

 * @priority:

 *	int, log priority.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_context_log_priority_set(struct iscsi_context *ctx,

						 int priority);

/**

 * iscsi_context_log_priority_get() - Get log priority.

 *

 * Retrieve current log priority. Valid log priority values are:

 *

 *	* LIBISCSI_LOG_PRIORITY_ERROR -- 3

 *

 *	* LIBISCSI_LOG_PRIORITY_WARNING -- 4

 *

 *	* LIBISCSI_LOG_PRIORITY_INFO -- 5

 *

 *	* LIBISCSI_LOG_PRIORITY_DEBUG -- 7

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 *

 * Return:

 *	int, log priority.

 */

__DLL_EXPORT int iscsi_context_log_priority_get(struct iscsi_context *ctx);

/**

 * iscsi_context_log_func_set() - Set log handler function.

 *

 * Set custom log handler. The log handler will be invoked when log message

 * is equal or more important(less value) than log priority setting.

 * Please check manpage libopeniscsiusr.h(3) for detail usage.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @log_func:

 *	Pointer of log handler function.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_context_log_func_set

	(struct iscsi_context *ctx,

	 void (*log_func) (struct iscsi_context *ctx, int priority,

			   const char *file, int line, const char *func_name,

			   const char *format, va_list args));

/**

 * iscsi_context_userdata_set() - Set user data pointer.

 *

 * Store user data pointer into 'struct iscsi_context'.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @userdata:

 *	Pointer of user defined data.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_context_userdata_set(struct iscsi_context *ctx,

					     void *userdata);

/**

 * iscsi_context_userdata_get() - Get user data pointer.

 *

 * Retrieve user data pointer from 'struct iscsi_context'.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 *

 * Return:

 *	void *. Pointer of user defined data.

 */

__DLL_EXPORT void *iscsi_context_userdata_get(struct iscsi_context *ctx);

/**

 * iscsi_sessions_get() - Retrieve all iSCSI sessions.

 *

 * Retrieves all iSCSI sessions. For the properties of 'struct iscsi_session',

 * please refer to the functions defined in 'libopeniscsiusr_session.h' file.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @ses:

 *	Output pointer of 'struct iscsi_session' pointer array. Its memory

 *	should be freed by iscsi_sessions_free().

 *	If this pointer is NULL, your program will be terminated by assert.

 * @se_count:

 *	Output pointer of uint32_t. Will store the size of

 *	'struct iscsi_session' pointer array.

 *

 * Return:

 *	int. Valid error codes are:

 *

 *	* LIBISCSI_OK

 *

 *	* LIBISCSI_ERR_BUG

 *

 *	* LIBISCSI_ERR_NOMEM

 *

 *	* LIBISCSI_ERR_ACCESS

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP

 *

 *	Error number could be converted to string by iscsi_strerror().

 */

__DLL_EXPORT int iscsi_sessions_get(struct iscsi_context *ctx,

				    struct iscsi_session ***ses,

				    uint32_t *se_count);

/**

 * iscsi_sessions_free() - Free the memory of 'struct iscsi_session' pointer

 * array

 *

 * Free the memory of 'iscsi_session' pointer array generated by

 * 'iscsi_sessions_get()'.

 * If provided 'ses' pointer is NULL or 'session_count' is 0, do nothing.

 *

 * @ses:

 *	Pointer of 'struct iscsi_session' pointer array.

 * @session_count:

 *	uint32_t, the size of 'struct iscsi_session' pointer array.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_sessions_free(struct iscsi_session **ses,

				      uint32_t session_count);

/**

 * iscsi_session_get() - Retrieve specified iSCSI sessions.

 *

 * Retrieves specified iSCSI sessions. For the properties of

 * 'struct iscsi_session', please refer to the functions defined in

 * 'libopeniscsiusr_session.h' file.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @sid:

 *	uint32_t, iSCSI session ID.

 * @se:

 *	Output pointer of 'struct iscsi_session' pointer. Its memory

 *	should be freed by iscsi_session_free().

 *	If this pointer is NULL, your program will be terminated by assert.

 *	If specified iSCSI session does not exists, this pointer will be set to

 *	NULL with LIBISCSI_OK returned.

 *

 * Return:

 *	int. Valid error codes are:

 *

 *	* LIBISCSI_OK

 *

 *	* LIBISCSI_ERR_BUG

 *

 *	* LIBISCSI_ERR_NOMEM

 *

 *	* LIBISCSI_ERR_ACCESS

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP

 *

 *	* LIBISCSI_ERR_SESS_NOT_FOUND

 *

 *	Error number could be converted to string by iscsi_strerror().

 */

__DLL_EXPORT int iscsi_session_get(struct iscsi_context *ctx, uint32_t sid,

				   struct iscsi_session **se);

/**

 * iscsi_session_free() - Free the memory of 'struct iscsi_session'.

 *

 * Free the memory of 'iscsi_session' pointer generated by

 * 'iscsi_sessions_get()'.

 * If provided 'se' pointer is NULL, do nothing.

 *

 * @se:

 *	Pointer of 'struct iscsi_session' pointer.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_session_free(struct iscsi_session *se);

/**

 * iscsi_default_iface_setup() - Setup default iSCSI interfaces.

 *

 * Setup default iSCSI interfaces for iSCSI TCP, iSER and iSCSI hardware offload

 * cards. It is required after new iSCSI hardware offload card installed.

 *

 * Below kernel modules will be loaded when required by this function:

 *

 *	* cxgb3i

 *	* cxgb4i

 *	* bnx2i

 *

 * It will also create configuration files for iSCSI hardware offload cards in

 * /var/lib/iscsi/ifaces/<iface_name>.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *

 * Return:

 *	int. Valid error codes are:

 *

 *	* LIBISCSI_OK

 *

 *	* LIBISCSI_ERR_BUG

 *

 *	* LIBISCSI_ERR_NOMEM

 *

 *	* LIBISCSI_ERR_ACCESS

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP

 *

 *	* LIBISCSI_ERR_IDBM

 *

 *	Error number could be converted to string by iscsi_strerror().

 */

__DLL_EXPORT int iscsi_default_iface_setup(struct iscsi_context *ctx);

/**

 * iscsi_ifaces_get() - Retrieve all iSCSI interfaces.

 *

 * Retrieves all iSCSI interfaces. For the properties of 'struct iscsi_iface',

 * please refer to the functions defined in 'libopeniscsiusr_iface.h' file.

 * The returned results contains default iSCSI interfaces(iser and iscsi_tcp)

 * and iSCSI interfaces configured in "/var/lib/iscsi/ifaces/".

 * Illegal configuration file will be skipped and warned.

 * To generate iSCSI interface configuration when new card installed, please

 * use iscsi_default_iface_setup().

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @ifaces:

 *	Output pointer of 'struct iscsi_iface' pointer array. Its memory

 *	should be freed by iscsi_ifaces_free().

 *	If this pointer is NULL, your program will be terminated by assert.

 * @iface_count:

 *	Output pointer of uint32_t. Will store the size of

 *	'struct iscsi_iface' pointer array.

 *

 * Return:

 *	int. Valid error codes are:

 *

 *	* LIBISCSI_OK

 *

 *	* LIBISCSI_ERR_BUG

 *

 *	* LIBISCSI_ERR_NOMEM

 *

 *	* LIBISCSI_ERR_ACCESS

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP

 *

 *	Error number could be converted to string by iscsi_strerror().

 */

__DLL_EXPORT int iscsi_ifaces_get(struct iscsi_context *ctx,

				  struct iscsi_iface ***ifaces,

				  uint32_t *iface_count);

/**

 * iscsi_ifaces_free() - Free the memory of 'struct iscsi_iface' pointer

 * array

 *

 * Free the memory of 'iscsi_iface' pointer array generated by

 * 'iscsi_ifaces_get()'.

 * If provided 'ifaces' pointer is NULL or 'iface_count' is 0, do nothing.

 *

 * @ifaces:

 *	Pointer of 'struct iscsi_iface' pointer array.

 * @iface_count:

 *	uint32_t, the size of 'struct iscsi_iface' pointer array.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_ifaces_free(struct iscsi_iface **ifaces,

				    uint32_t iface_count);

/**

 * iscsi_iface_get() - Retrieve specified iSCSI interface.

 *

 * Retrieves specified iSCSI interfaces by reading configuration from

 * "/var/lib/iscsi/iface/<iface_name>".

 * To generate iSCSI interface configuration when new card installed, please

 * use iscsi_default_iface_setup().

 * Illegal configuration file will be treated as error LIBISCSI_ERR_IDBM.

 * Configuration file not found will be treated as error LIBISCSI_ERR_INVAL.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @iface_name:

 *	String. Name of iSCSI interface. Also the file name of configuration

 *	file "/var/lib/iscsi/iface/<iface_name>".

 *	If this pointer is NULL or empty string, your program will be terminated

 *	by assert.

 * @iface:

 *	Output pointer of 'struct iscsi_iface'. Its memory should be freed by

 *	iscsi_iface_free().

 *	If this pointer is NULL, your program will be terminated by assert.

 *

 * Return:

 *	int. Valid error codes are:

 *

 *	* LIBISCSI_OK

 *

 *	* LIBISCSI_ERR_BUG

 *

 *	* LIBISCSI_ERR_NOMEM

 *

 *	* LIBISCSI_ERR_ACCESS

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP

 *

 *	* LIBISCSI_ERR_IDBM

 *

 *	Error number could be converted to string by iscsi_strerror().

 */

__DLL_EXPORT int iscsi_iface_get(struct iscsi_context *ctx,

				 const char *iface_name,

				 struct iscsi_iface **iface);

/**

 * iscsi_iface_free() - Free the memory of 'struct iscsi_iface' pointer.

 *

 * Free the memory of 'iscsi_iface' pointer generated by 'iscsi_iface_get()'.

 * If provided 'iface' pointer is NULL, do nothing.

 *

 * @iface:

 *	Pointer of 'struct iscsi_iface' pointer.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_iface_free(struct iscsi_iface *iface);

/**

 * iscsi_nodes_get() - Retrieve all iSCSI nodes.

 *

 * Retrieves all iSCSI nodes. For the properties of 'struct iscsi_node',

 * please refer to the functions defined in 'libopeniscsiusr_node.h' file.

 * The returned results contains iSCSI nodes configured in "/etc/iscsi/nodes/".

 * Illegal configuration file will be skipped and warned.

 * The returned 'struct iscsi_node' pointer array is sorted by target name,

 * connection address, connection port and interface.

 *

 * @ctx:

 *	Pointer of 'struct iscsi_context'.

 *	If this pointer is NULL, your program will be terminated by assert.

 * @nodes:

 *	Output pointer of 'struct iscsi_node' pointer array. Its memory

 *	should be freed by iscsi_nodes_free().

 *	If this pointer is NULL, your program will be terminated by assert.

 * @node_count:

 *	Output pointer of uint32_t. Will store the size of

 *	'struct iscsi_node' pointer array.

 *

 * Return:

 *	int. Valid error codes are:

 *

 *	* LIBISCSI_OK

 *

 *	* LIBISCSI_ERR_BUG

 *

 *	* LIBISCSI_ERR_NOMEM

 *

 *	* LIBISCSI_ERR_ACCESS

 *

 *	* LIBISCSI_ERR_SYSFS_LOOKUP

 *

 *	* LIBISCSI_ERR_IDBM

 *

 *	Error number could be converted to string by iscsi_strerror().

 */

__DLL_EXPORT int iscsi_nodes_get(struct iscsi_context *ctx,

				 struct iscsi_node ***nodes,

				 uint32_t *node_count);

/**

 * iscsi_nodes_free() - Free the memory of 'struct iscsi_node' pointer

 * array

 *

 * Free the memory of 'iscsi_node' pointer array generated by

 * 'iscsi_nodes_get()'.

 * If provided 'nodes' pointer is NULL or 'node_count' is 0, do nothing.

 *

 * @nodes:

 *	Pointer of 'struct iscsi_node' pointer array.

 * @node_count:

 *	uint32_t, the size of 'struct iscsi_node' pointer array.

 *

 * Return:

 *	void

 */

__DLL_EXPORT void iscsi_nodes_free(struct iscsi_node **nodes,

				   uint32_t node_count);

#ifdef __cplusplus

} /* End of extern "C" */

#endif

#endif /* End of _LIB_OPEN_ISCSI_USR_H_ */