Current File : //usr/include/config_admin.h

/*
 * Copyright (c) 1998, 2014, Oracle and/or its affiliates. All rights reserved.
 */

#ifndef _CONFIG_ADMIN_H
#define	_CONFIG_ADMIN_H

/*
 * config_admin.h
 *
 * this file supports usage of the interfaces defined in
 * config_admin.3x. which are contained in /usr/lib/libcfgadm.so.1
 */

#include <sys/param.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Defined constants
 */
#define	CFGA_DYN_SEP		"::"

/*
 * Configuration change state commands
 */
typedef enum {
	CFGA_CMD_NONE = 0,
	CFGA_CMD_LOAD,
	CFGA_CMD_UNLOAD,
	CFGA_CMD_CONNECT,
	CFGA_CMD_DISCONNECT,
	CFGA_CMD_CONFIGURE,
	CFGA_CMD_UNCONFIGURE
} cfga_cmd_t;

/*
 * Configuration states
 */
typedef enum {
	CFGA_STAT_NONE = 0,
	CFGA_STAT_EMPTY,
	CFGA_STAT_DISCONNECTED,
	CFGA_STAT_CONNECTED,
	CFGA_STAT_UNCONFIGURED,
	CFGA_STAT_CONFIGURED
} cfga_stat_t;

/*
 * Configuration conditions
 */
typedef enum {
	CFGA_COND_UNKNOWN = 0,
	CFGA_COND_OK,
	CFGA_COND_FAILING,
	CFGA_COND_FAILED,
	CFGA_COND_UNUSABLE
} cfga_cond_t;

/*
 * Flags
 */
#define	CFGA_FLAG_FORCE		0x01
#define	CFGA_FLAG_VERBOSE	0x02
#define	CFGA_FLAG_LIST_ALL	0x04

/*
 * Library function error codes returned by all functions below
 * except config_strerror which is used to decode the error
 * codes.
 */
typedef enum {
	CFGA_OK = 0,
	CFGA_NACK,
	CFGA_NOTSUPP,
	CFGA_OPNOTSUPP,
	CFGA_PRIV,
	CFGA_BUSY,
	CFGA_SYSTEM_BUSY,
	CFGA_DATA_ERROR,
	CFGA_LIB_ERROR,
	CFGA_NO_LIB,
	CFGA_INSUFFICENT_CONDITION,
	CFGA_INVAL,
	CFGA_ERROR,
	CFGA_APID_NOEXIST,
	CFGA_ATTR_INVAL
} cfga_err_t;

/*
 * Attachment point specifier types.
 */
typedef enum {
	UNKNOWN_AP,
	LOGICAL_LINK_AP,
	LOGICAL_DRV_AP,
	PHYSICAL_AP,
	AP_TYPE
} cfga_ap_types_t;

struct cfga_confirm {
	int (*confirm)(void *appdata_ptr, const char *message);
	void *appdata_ptr;
};

struct cfga_msg {
	int (*message_routine)(void *appdata_ptr, const char *message);
	void *appdata_ptr;
};

/*
 * There are 4 version of the list data defined in this header file.
 *
 * - V1 (PSARC 1996/285)
 *   The primary listing interface was config_stat(3X) and config_list(3X)
 * which uses cfga_stat_data structure. It has most of the currently available
 * members:
 *
 *  cfga_ap_log_id_t	ap_log_id	[CFGA_AP_LOG_ID_LEN]	20
 *  cfga_ap_phys_id_t  	ap_phys_id	[CFGA_AP_PHYS_ID_LEN]	1028
 *  cfga_stat_t		ap_r_state	int
 *  cfga_stat_t		ap_o_state	int
 *  cfga_cond_t		ap_cond		int
 *  cfga_busy_t		ap_busy		int
 *  time_t		ap_status_time	tiem_t
 *  cfga_info_t		ap_info		[CFGA_INFO_LEN]		4096
 *  cfga_type_t		ap_type		[CFGA_TYPE_LEN]		12
 *
 * - V2 (PSARC 1998/423)
 *   The cfga_stat_data structure and its interfaces were deprecated, and
 * cfga_list_data structure was introduced. The listing interface is
 * config_list_ext(3X). It is a simple extension from cfga_stat_data using
 * same member name but different size. The differences from cfga_stat_data
 * include:
 *
 * Expanded:
 *  cfga_log_ext_t	ap_log_id	[CFGA_LOG_EXT_LEN]	30
 *  cfga_phys_ext_t	ap_phys_id	[CFGA_PHYS_EXT_LEN]	1028 + 30
 * Added:
 *  cfga_class_t	ap_class	[CFGA_CLASS_LEN]	12
 *
 * - V3
 *   This is a simple expansion from V2 data. The purpose of this interface
 * is to provide a way that existing plugins can supply longer names with
 * same code basis. This interface is not public, but for compatibility and
 * convenience for the ON components. The expanded structure is provided as
 * cfga_list_data_v3. The config_list_v3() function can be specifically used
 * for this data structure, though it is not the public interface. The
 * plugins take advantage of this transitional interface has to set
 * CFGA_HSL_V3 to cfga_version. The differences from cfga_list_data include:
 *
 *  cfga_log_ext_t	ap_log_id	[CFGA_LOG_EXT_LEN_V3]	256
 *  cfga_phys_ext_t	ap_phys_id	[CFGA_PHYS_EXT_LEN_V3]	1028 + 256
 *  cfga_class_t	ap_class	[CFGA_CLASS_LEN_V3]	256
 *  cfga_type_t		ap_type		[CFGA_TYPE_LEN_V3]	256
 *
 * - V4 (PSARC 2013/286)
 *   This version intends to remove the fixed size buffer and array based
 * interface of config_list_ext(3X). The cfga_apinfo_t structure is
 * introduced, which has pointers to string where they used to be fixed size
 * array. The name of structure member remains same. The new interface
 * cfgadm_apinfo_iter() will calls into the callback function with supplying
 * a pointer to cfga_apinfo_t structure. The given cfga_apinfo_t can be
 * duplicated using config_apinfo_dup() and released by config_apinfo_free().
 * The plugins which utilize this interface has to set CFGA_HSL_V4 to
 * cfga_version.
 */

/*
 * Plugin version information.
 */
#define	CFGA_HSL_V1	1
#define	CFGA_HSL_V2	2
#define	CFGA_HSL_V3	3
#define	CFGA_HSL_V4	4
#define	CFGA_HSL_VERS	CFGA_HSL_V4

#ifndef _CFGA_HSL_DEF_VERS
#define	_CFGA_HSL_DEF_VERS CFGA_HSL_V4
#endif

/* cfga_info_t has same size in all versions */
#define	CFGA_INFO_LEN		4096

/*
 * V1 and V2 data
 */
#define	CFGA_AP_LOG_ID_LEN	20
#define	CFGA_AP_PHYS_ID_LEN	MAXPATHLEN
#define	CFGA_TYPE_LEN_V12	12

/* V2 length */
#define	CFGA_CLASS_LEN_V2	12
#define	CFGA_LOG_EXT_LEN_V2	30
#define	CFGA_PHYS_EXT_LEN_V2	(CFGA_AP_PHYS_ID_LEN + CFGA_LOG_EXT_LEN_V2)

/* V3 length */
#define	CFGA_TYPE_LEN_V3	MAXNAMELEN
#define	CFGA_CLASS_LEN_V3	MAXNAMELEN
#define	CFGA_LOG_EXT_LEN_V3	MAXPATHLEN
#define	CFGA_PHYS_EXT_LEN_V3	(CFGA_AP_PHYS_ID_LEN + CFGA_LOG_EXT_LEN_V3)

/*
 * common data type
 */
typedef int cfga_flags_t;
typedef int cfga_busy_t;
typedef char cfga_info_t[CFGA_INFO_LEN];

/*
 * The following type are actually V1 interface. However, it is used in the
 * function prototype. Therefore, it needs to be always exposed even in
 * the V3 trasition mode.
 */
typedef char cfga_ap_log_id_t[CFGA_AP_LOG_ID_LEN];

/*
 * The current version is V4 as defined above.  By default, all data type
 * of 4 versions are exposed and visible from application. In case a cfgadm
 * plugin would like to take advantage of the transitional interface (V3),
 * _CFGA_HSL_DEF_VERS can be set to 3. In such case, V1 and V2 data types are
 * not exposed, and cfga_list_data_t transparently becomes V3 data type.
 * The cfga_version in the plugin needs to be set to CFGA_HSL_V3, so that
 * libcfgadm can identify V3 plugin.
 */
#if _CFGA_HSL_DEF_VERS != CFGA_HSL_V3
/*
 * V1 data type
 * V1 structures/definitions are retained for backward compatibility
 */
typedef char cfga_type_t[CFGA_TYPE_LEN_V12];

typedef char cfga_ap_phys_id_t[CFGA_AP_PHYS_ID_LEN];

typedef struct cfga_stat_data {
	cfga_ap_log_id_t ap_log_id;	/* Attachment point logical id */
	cfga_ap_phys_id_t ap_phys_id;	/* Attachment point physical id */
	cfga_stat_t	ap_r_state;	/* Receptacle state */
	cfga_stat_t	ap_o_state;	/* Occupant state */
	cfga_cond_t	ap_cond;	/* Attachment point condition */
	cfga_busy_t	ap_busy;	/* Busy indicators */
	time_t		ap_status_time;	/* Attachment point last change */
	cfga_info_t	ap_info;	/* Miscellaneous information */
	cfga_type_t	ap_type;	/* Occupant type */
} cfga_stat_data_t;

/*
 * V2 data type.
 */
typedef char cfga_class_t[CFGA_CLASS_LEN_V2];
typedef char cfga_log_ext_t[CFGA_LOG_EXT_LEN_V2];
typedef char cfga_phys_ext_t[CFGA_PHYS_EXT_LEN_V2];

typedef struct cfga_list_data {
	cfga_log_ext_t 	ap_log_id;	/* Attachment point logical id */
	cfga_phys_ext_t	ap_phys_id;	/* Attachment point physical id */
	cfga_class_t 	ap_class;	/* Attachment point class */
	cfga_stat_t	ap_r_state;	/* Receptacle state */
	cfga_stat_t	ap_o_state;	/* Occupant state */
	cfga_cond_t	ap_cond;	/* Attachment point condition */
	cfga_busy_t	ap_busy;	/* Busy indicators */
	time_t		ap_status_time;	/* Attachment point last change */
	cfga_info_t	ap_info;	/* Miscellaneous information */
	cfga_type_t	ap_type;	/* Occupant type */
} cfga_list_data_v2_t;

#endif /* _CFGA_HSL_DEF_VERS != CFGA_HSL_V3 */

/*
 * V3 data type
 */
typedef char cfga_type_v3_t[CFGA_TYPE_LEN_V3];
typedef char cfga_class_v3_t[CFGA_CLASS_LEN_V3];
typedef char cfga_log_ext_v3_t[CFGA_LOG_EXT_LEN_V3];
typedef char cfga_phys_ext_v3_t[CFGA_PHYS_EXT_LEN_V3];

typedef struct cfga_list_data_v3 {
	int	__ap_plugin_vers;	/* reserved internal */
	cfga_log_ext_v3_t ap_log_id;	/* Attachment point logical id */
	cfga_phys_ext_v3_t ap_phys_id;	/* Attachment point physical id */
	cfga_class_v3_t	ap_class;	/* Attachment point class */
	cfga_stat_t	ap_r_state;	/* Receptacle state */
	cfga_stat_t	ap_o_state;	/* Occupant state */
	cfga_cond_t	ap_cond;	/* Attachment point condition */
	cfga_busy_t	ap_busy;	/* Busy indicators */
	time_t		ap_status_time;	/* Attachment point last change */
	cfga_info_t	ap_info;	/* Miscellaneous information */
	cfga_type_v3_t	ap_type;	/* Occupant type */
	int		__ap_pad[16];	/* reserved internal */
} cfga_list_data_v3_t;

/*
 * The cfga_list_data structure and macros in user application remains V2
 * by default.
 */
#if _CFGA_HSL_DEF_VERS != CFGA_HSL_V3
typedef cfga_list_data_v2_t	cfga_list_data_t;
#else
typedef cfga_list_data_v3_t	cfga_list_data_t;
/* There may be references to following types. They should also be V3. */
typedef cfga_type_v3_t		cfga_type_t;
typedef cfga_class_v3_t		cfga_class_t;
typedef cfga_log_ext_v3_t	cfga_log_ext_t;
typedef cfga_phys_ext_v3_t	cfga_phys_ext_t;
#endif

#if _CFGA_HSL_DEF_VERS != CFGA_HSL_V3
#define	CFGA_TYPE_LEN		CFGA_TYPE_LEN_V12
#define	CFGA_CLASS_LEN		CFGA_CLASS_LEN_V2
#define	CFGA_LOG_EXT_LEN	CFGA_LOG_EXT_LEN_V2
#define	CFGA_PHYS_EXT_LEN	CFGA_PHYS_EXT_LEN_V2
#else
#define	CFGA_TYPE_LEN		CFGA_TYPE_LEN_V3
#define	CFGA_CLASS_LEN		CFGA_CLASS_LEN_V3
#define	CFGA_LOG_EXT_LEN	CFGA_LOG_EXT_LEN_V3
#define	CFGA_PHYS_EXT_LEN	CFGA_PHYS_EXT_LEN_V3
#endif

/*
 * V4 data type
 */
typedef struct cfga_apinfo {
	int	__ap_data_vers;		/* reserved internal */
	int	__ap_plugin_vers;	/* reserved internal */
	char	*ap_log_id;		/* Attachment point logical id */
	char	*ap_phys_id;		/* Attachment point physical id */
	char	*ap_class;		/* Attachment point class */
	char	*ap_info;		/* Miscellaneous information */
	char	*ap_type;		/* Occupant type */
	cfga_stat_t	ap_r_state;	/* Receptacle state */
	cfga_stat_t	ap_o_state;	/* Occupant state */
	cfga_cond_t	ap_cond;	/* Attachment point condition */
	cfga_busy_t	ap_busy;	/* Busy indicators */
	time_t	ap_status_time;		/* Attachment point last change */
	int	__ap_pad2[10];		/* reserved internal */
	struct cfga_apinfo *__ap_next;	/* reserved internal */
} cfga_apinfo_t;


#if defined(__STDC__)

/*
 * config_admin.3x public library interfaces
 */
extern cfga_err_t config_change_state(cfga_cmd_t state_change_cmd,
    int num_ap_ids, char *const *ap_ids, const char *options,
    struct cfga_confirm *confp, struct cfga_msg *msgp, char **errstring,
    cfga_flags_t flags);

extern cfga_err_t config_private_func(const char *function, int num_ap_ids,
    char *const *ap_ids, const char *options, struct cfga_confirm *confp,
    struct cfga_msg *msgp, char **errstring, cfga_flags_t flags);

extern cfga_err_t config_test(int num_ap_ids, char *const *ap_ids,
    const char *options, struct cfga_msg *msgp, char **errstring,
    cfga_flags_t flags);

extern cfga_err_t config_list_ext(int num_ap_ids, char *const *ap_ids,
    cfga_list_data_t **ap_id_list, int *nlist, const char *options,
    const char *listopts, char **errstring, cfga_flags_t flags);

extern cfga_err_t config_apinfo_iter(const char *ap_id,
    int (*listcb)(cfga_apinfo_t *ap, void *arg), void *arg,
    const char *options, const char *listopts,
    char **errstring, cfga_flags_t flags);

extern cfga_apinfo_t *config_apinfo_dup(cfga_apinfo_t *ap);
extern void config_apinfo_free(cfga_apinfo_t *ap);
extern cfga_err_t config_plugin_apinfo_add(void *, cfga_apinfo_t *);

extern cfga_err_t config_help(int num_ap_ids, char *const *ap_ids,
    struct cfga_msg *msgp, const char *options, cfga_flags_t flags);

extern const char *config_strerror(cfga_err_t cfgerrnum);

extern int config_ap_id_cmp(const cfga_ap_log_id_t ap_id1,
    const cfga_ap_log_id_t ap_id2);

extern void config_unload_libs(void);

/*
 * Private interfaces
 */
extern cfga_err_t config_list_v3(int num_ap_ids, char *const *ap_ids,
    cfga_list_data_v3_t **ap_id_list, int *nlist, const char *options,
    const char *listopts, char **errstring, cfga_flags_t flags);

extern cfga_ap_types_t config_find_arg_type(const char *ap_id);

#if _CFGA_HSL_DEF_VERS != CFGA_HSL_V3
/*
 * The following two routines are retained only for backward compatibility
 * We don't expose these interfaces in transitional mode (V3).
 */
extern cfga_err_t config_stat(int num_ap_ids, char *const *ap_ids,
    struct cfga_stat_data *buf, const char *options, char **errstring);

extern cfga_err_t config_list(struct cfga_stat_data **ap_di_list, int *nlist,
    const char *options, char **errstring);
#endif

#ifdef CFGA_PLUGIN_LIB
/*
 * Plugin library routine hooks - only to be used by the generic
 * library and plugin libraries (who must define CFGA_PLUGIN_LIB
 * prior to the inclusion of this header).
 */

extern cfga_err_t cfga_change_state(cfga_cmd_t, const char *, const char *,
    struct cfga_confirm *, struct cfga_msg *, char **, cfga_flags_t);
extern cfga_err_t cfga_private_func(const char *, const char *, const char *,
    struct cfga_confirm *, struct cfga_msg *, char **, cfga_flags_t);
extern cfga_err_t cfga_test(const char *, const char *, struct cfga_msg *,
    char **, cfga_flags_t);
extern cfga_err_t cfga_list_ext(const char *, cfga_list_data_t **, int *,
    const char *, const char *, char **, cfga_flags_t);
extern cfga_err_t cfga_plugin_apinfo(const char *, void *,
    const char *, const char *, char **, cfga_flags_t);
extern cfga_err_t cfga_help(struct cfga_msg *, const char *, cfga_flags_t);
extern int cfga_ap_id_cmp(const cfga_ap_log_id_t, const cfga_ap_log_id_t);

#if _CFGA_HSL_DEF_VERS != CFGA_HSL_V3
/*
 * The following two routines are retained only for backward compatibility.
 * We don't expose these interfaces in transitional mode (V3).
 */
extern cfga_err_t cfga_stat(const char *, struct cfga_stat_data *,
    const char *, char **);
extern cfga_err_t cfga_list(const char *, struct cfga_stat_data **, int *,
    const char *, char **);
#endif

#endif /* CFGA_PLUGIN_LIB */

#else /* !defined __STDC__ */

extern const char *config_strerror();
extern int config_ap_id_cmp();

#endif /* __STDC__ */

#ifdef __cplusplus
}
#endif

#endif /* _CONFIG_ADMIN_H */