/*

 * iSCSI Administration library

 *

 * Copyright (C) 2008-2009 Red Hat, Inc. All rights reserved.

 * Copyright (C) 2008-2009 Hans de Goede <hdegoede@redhat.com>

 * Copyright (C) 2015      Peter Hatina <phatina@redhat.com>

 * maintained by open-iscsi@googlegroups.com

 *

 * 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 2 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.

 *

 * See the file COPYING included with this distribution for more details.

 */

#ifndef __LIBISCSI_H

#define __LIBISCSI_H

#include <netdb.h>

#ifdef __cplusplus

extern "C" {

#endif /* __cplusplus */

#if __GNUC__ >= 4

#define PUBLIC __attribute__ ((visibility("default")))

#else

#define PUBLIC

#endif

/** \brief Maximum length for iSCSI values.

 *

 * Maximum length for iSCSI values such as hostnames and parameter values.

 */

#define LIBISCSI_VALUE_MAXLEN 256

/** \brief supported authentication methods

 *

 * This enum lists all supported authentication methods.

 */

enum libiscsi_auth_t {

    libiscsi_auth_none   /** No authentication */,

    libiscsi_auth_chap   /** CHAP authentication */,

};

/** \brief libiscsi context struct

 *

 * Note: even though libiscsi uses a context struct, the underlying open-iscsi

 * code does not, so libiscsi is not thread safe, not even when using one

 * context per thread!

 */

struct libiscsi_context;

/** \brief iSCSI session timeouts

 *

 * Struct holding session timeouts.

 */

struct libiscsi_session_timeout {

    int abort_tmo;

    int lu_reset_tmo;

    int recovery_tmo;

    int tgt_reset_tmo;

};

/** \brief iSCSI node record

 *

 * Struct holding data uniquely identifying an iSCSI node.

 */

struct libiscsi_node {

    char name[LIBISCSI_VALUE_MAXLEN]     /** iSCSI iqn for the node. */;

    int tpgt                             /** Portal group number. */;

    /* Note open-iscsi has some code in place for multiple connections in one

       node record and thus multiple address / port combi's, but this does not

       get used anywhere, so we keep things simple and assume one connection */

    char address[NI_MAXHOST]             /** Portal hostname or IP-address. */;

    int port                             /** Portal port number. */;

    char iface[LIBISCSI_VALUE_MAXLEN]    /** Interface to connect through. */;

};

/** \brief libiscsi CHAP authentication information struct

 *

 * Struct holding all data needed for CHAP login / authentication. Note that

 * \e reverse_username may be a 0 length string in which case only forward

 * authentication will be done.

 */

struct libiscsi_chap_auth_info {

    char username[LIBISCSI_VALUE_MAXLEN]         /** Username */;

    char password[LIBISCSI_VALUE_MAXLEN]         /** Password */;

    char reverse_username[LIBISCSI_VALUE_MAXLEN] /** Reverse Username */;

    char reverse_password[LIBISCSI_VALUE_MAXLEN] /** Reverse Password */;

};

/** \brief iSCSI session

 *

 * Struct hoding iSCSI session information.

 */

struct libiscsi_session_info {

    int sid;

    struct libiscsi_session_timeout tmo;

    struct libiscsi_chap_auth_info chap;

    char targetname[LIBISCSI_VALUE_MAXLEN];

    int tpgt;

    char address[NI_MAXHOST];

    int port;

    char persistent_address[NI_MAXHOST];

    int persistent_port;

};

/** \brief generic libiscsi authentication information struct

 *

 * Struct holding authentication information for discovery and login.

 */

struct libiscsi_auth_info {

    enum libiscsi_auth_t method /** Authentication method to use */;

    union {

        struct libiscsi_chap_auth_info chap /** Chap specific info */;

    } /** Union holding method depenend info */;

};

/** \brief Initalize libiscsi

 *

 * This function creates a libiscsi context and initalizes it. This context

 * is need to use other libiscsi funtions.

 *

 * \return     A pointer to the created context, or NULL in case of an error.

 */

PUBLIC struct libiscsi_context *libiscsi_init(void);

/** \brief Cleanup libiscsi used resource

 *

 * This function cleanups any used resources and then destroys the passed

 * context. After this the passed in context may no longer be used!

 *

 * \param context                libiscsi context to operate on.

 */

PUBLIC void libiscsi_cleanup(struct libiscsi_context *context);

/** \brief Discover iSCSI nodes using sendtargets and add them to the node db.

 *

 * This function connects to the given address and port and then tries to

 * discover iSCSI nodes using the sendtargets protocol. Any found nodes are

 * added to the local iSCSI node database and are returned in a dynamically

 * allocated array.

 *

 * Note that the (optional) authentication info is for authenticating the

 * discovery, and is not for the found nodes! If the connection(s) to the

 * node(s) need authentication too, you can set the username / password for

 * those (which can be different!) using the libiscsi_node_set_auth() function.

 *

 * \param context                libiscsi context to operate on.

 * \param address                Hostname or IP-address to connect to.

 * \param port                   Port to connect to, or 0 for the default port.

 * \param auth_info              Authentication information, or NULL.

 * \param nr_found		 The number of found nodes will be returned

 *                               through this pointer if not NULL.

 * \param found_nodes            The address of the dynamically allocated array

 *                               of found nodes will be returned through this

 *                               pointer if not NULL. The caller must free this

 *                               array using free().

 * \return                       0 on success, otherwise a standard error code

 *                               (from errno.h).

 */

PUBLIC int libiscsi_discover_sendtargets(struct libiscsi_context *context,

    const char *address, int port, const struct libiscsi_auth_info *auth_info,

    int *nr_found, struct libiscsi_node **found_nodes);

/** \brief Read iSCSI node info from firmware and add them to the node db.

 *

 * This function discovers iSCSI nodes using firmware (ppc or ibft). Any found

 * nodes are added to the local iSCSI node database and are returned in a

 * dynamically allocated array.

 *

 * Note that unlike sendtargets discovery, this function will also read

 * authentication info and store that in the database too.

 *

 * Note this function currently is a stub which will always return -EINVAL

 * (IOW it is not yet implemented)

 *

 * \param context                libiscsi context to operate on.

 * \param nr_found		 The number of found nodes will be returned

 *                               through this pointer if not NULL.

 * \param found_nodes            The address of the dynamically allocated array

 *                               of found nodes will be returned through this

 *                               pointer if not NULL. The caller must free this

 *                               array using free().

 * \return                       0 on success, otherwise a standard error code

 *                               (from errno.h).

 */

PUBLIC int libiscsi_discover_firmware(struct libiscsi_context *context,

    int *nr_found, struct libiscsi_node **found_nodes);

/** \brief Check validity of the given authentication info.

 *

 * This function checks the validity of the given authentication info. For 

 * example in case of CHAP, if the username and password are not empty.

 *

 * This function is mainly intended for use by language bindings.

 *

 * \param context                libiscsi context to operate on.

 * \param auth_info              Authentication information to check.

 * \return                       0 on success, otherwise EINVAL.

 */

PUBLIC int libiscsi_verify_auth_info(struct libiscsi_context *context,

	const struct libiscsi_auth_info *auth_info);

/** \brief Set the authentication info for the given node.

 *

 * This function sets the authentication information for the node described by

 * the given node record. This will overwrite any existing authentication

 * information.

 *

 * This is the way to specify authentication information for nodes found

 * through sendtargets discovery.

 *

 * Note:

 * 1) This is a convience wrapper around libiscsi_node_set_parameter(),

 *    setting the node.session.auth.* parameters.

 * 2) For nodes found through firmware discovery the authentication information

 *    has already been set from the firmware.

 * 3) \e auth_info may be NULL in which case any existing authinfo will be

 *    cleared.

 *

 * \param context                libiscsi context to operate on.

 * \param node                   iSCSI node to set auth information of

 * \param auth_info              Authentication information, or NULL.

 * \return                       0 on success, otherwise a standard error code

 *                               (from errno.h).

 */

PUBLIC int libiscsi_node_set_auth(struct libiscsi_context *context,

    const struct libiscsi_node *node,

    const struct libiscsi_auth_info *auth_info);

/** \brief Get the authentication info for the given node.

 *

 * This function gets the authentication information for the node described by

 * the given node record.

 *

 * \param context                libiscsi context to operate on.

 * \param node                   iSCSI node to set auth information of

 * \param auth_info              Pointer to a libiscsi_auth_info struct where

 *                               the retreived information will be stored.

 * \return                       0 on success, otherwise a standard error code

 *                               (from errno.h).

 */

PUBLIC int libiscsi_node_get_auth(struct libiscsi_context *context,

    const struct libiscsi_node *node,

    struct libiscsi_auth_info *auth_info);

/** \brief Login to an iSCSI node.

 *

 * Login to the iSCSI node described by the given node record.

 *

 * \param context       libiscsi context to operate on.

 * \param node          iSCSI node to login to.

 * \return              0 on success, otherwise a standard error code

 *                      (from errno.h).

 */

PUBLIC int libiscsi_node_login(struct libiscsi_context *context,

    const struct libiscsi_node *node);

/** \brief Logout of an iSCSI node.

 *

 * Logout of the iSCSI node described by the given node record.

 *

 * \param context       libiscsi context to operate on.

 * \param node          iSCSI node to logout from.

 * \return              0 on success, otherwise a standard error code

 *                      (from errno.h).

 */

PUBLIC int libiscsi_node_logout(struct libiscsi_context *context,

    const struct libiscsi_node *node);

/** \brief Get an array of iSCSI sessions.

 *

 * Get the array containing iSCSI sessions' information.

 *

 * \param context       libiscsi context to operate on.

 * \param infos         Array of iSCSI sessions' information.

 *                      Release with free().

 * \param nr_sessions   The number of elements in \e infos.

 * \return              0 on success, otherwise a standard error code

 *                      (from errno.h).

 */

PUBLIC int libiscsi_get_session_infos(struct libiscsi_context *context,

    struct libiscsi_session_info **infos, int *nr_sessions);

/** \brief Get session information by session ID.

 *

 * \param context       libiscsi context to operate on.

 * \param info          iSCSI session information.

 * \param session       Session name.

 * \return              0 on success, otherwise a standard error code

 *                      (from errno.h)

 */

PUBLIC int libiscsi_get_session_info_by_id(struct libiscsi_context *context,

    struct libiscsi_session_info *info,

    const char *session);

/** \brief Set an iSCSI parameter for the given node

 *

 * Set the given nodes iSCSI parameter named by \e parameter to value \e value.

 *

 * \param context       libiscsi context to operate on.

 * \param node          iSCSI node to change a parameter from.

 * \param parameter     Name of the parameter to set.

 * \param value         Value to set the parameter too.

 * \return              0 on success, otherwise a standard error code

 *                      (from errno.h).

 */

PUBLIC int libiscsi_node_set_parameter(struct libiscsi_context *context,

    const struct libiscsi_node *node,

    const char *parameter, const char *value);

/** \brief Get the value of an iSCSI parameter for the given node

 *

 * Get the value of the given nodes iSCSI parameter named by \e parameter.

 *

 * \param context       libiscsi context to operate on.

 * \param node          iSCSI node to change a parameter from.

 * \param parameter     Name of the parameter to get.

 * \param value         The retreived value is stored here, this buffer must be

 *                      atleast LIBISCSI_VALUE_MAXLEN bytes large.

 * \return              0 on success, otherwise a standard error code

 *                      (from errno.h).

 */

PUBLIC int libiscsi_node_get_parameter(struct libiscsi_context *context,

    const struct libiscsi_node *node, const char *parameter, char *value);

/** \brief Get human readable string describing the last libiscsi error.

 *

 * This function can be called to get a human readable error string when a

 * libiscsi function has returned an error. This function uses a single buffer

 * per context, thus the result is only valid as long as no other libiscsi

 * calls are made on the same context after the failing function call.

 *

 * \param context       libiscsi context to operate on.

 *

 * \return human readable string describing the last libiscsi error.

 */

PUBLIC const char *libiscsi_get_error_string(struct libiscsi_context *context);

/************************** Utility functions *******************************/

/** \brief libiscsi network config struct

 *

 * libiscsi network config struct.

 */

struct libiscsi_network_config {

    int dhcp                                  /** Using DHCP? (boolean). */;

    char iface_name[LIBISCSI_VALUE_MAXLEN]    /** Interface name. */;

    char mac_address[LIBISCSI_VALUE_MAXLEN]   /** MAC address. */;

    char ip_address[LIBISCSI_VALUE_MAXLEN]    /** IP address. */;

    char netmask[LIBISCSI_VALUE_MAXLEN]       /** Netmask. */;

    char gateway[LIBISCSI_VALUE_MAXLEN]       /** IP of Default gateway. */;

    char primary_dns[LIBISCSI_VALUE_MAXLEN]   /** IP of the Primary DNS. */;

    char secondary_dns[LIBISCSI_VALUE_MAXLEN] /** IP of the Secondary DNS. */;

};

/** \brief Get network configuration information from iscsi firmware

 *

 * Function can be called to get the network configuration information

 * (like dhcp, ip, netmask, default gateway, etc.) from the firmware of a

 * network adapter with iscsi boot firmware.

 *

 * Note that not all fields of the returned struct are necessarilly filled,

 * unset fields contain a 0 length string.

 *

 * \param config        pointer to a libiscsi_network_config struct to fill.

 *

 * \return              0 on success, ENODEV when no iscsi firmware was found.

 */

PUBLIC int libiscsi_get_firmware_network_config(

    struct libiscsi_network_config *config);

/** \brief Get the initiator name (iqn) from the iscsi firmware

 *

 * Get the initiator name (iqn) from the iscsi firmware.

 *

 * \param initiatorname The initiator name is stored here, this buffer must be

 *                      atleast LIBISCSI_VALUE_MAXLEN bytes large.

 * \return              0 on success, ENODEV when no iscsi firmware was found.

 */

PUBLIC int libiscsi_get_firmware_initiator_name(char *initiatorname);

#undef PUBLIC

#ifdef __cplusplus

}

#endif /* __cplusplus */

#endif