/*
* 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
* /etc/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 "/etc/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
* "/etc/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 "/etc/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_ */