/*****************************************************************************
* Copyright (c) 2004 Digi International Inc., All Rights Reserved
* 
* This software contains proprietary and confidential information of Digi
* International Inc.  By accepting transfer of this copy, Recipient agrees
* to retain this software in confidence, to prevent disclosure to others,
* and to make no use of this software other than that for which it was
* delivered.  This is an unpublished copyrighted work of Digi International
* Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly
* prohibited.
* 
* Restricted Rights Legend
*
* Use, duplication, or disclosure by the Government is subject to
* restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in
* Technical Data and Computer Software clause at DFARS 252.227-7031 or
* subparagraphs (c)(1) and (2) of the Commercial Computer Software -
* Restricted Rights at 48 CFR 52.227-19, as applicable.
*
* Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
*
*****************************************************************************/

#ifndef snmpv3api_h
#define snmpv3api_h

#ifdef __cplusplus
extern "C"
{
#endif

#include "Npttypes.h"
#include "nastatus.h"
#include "snmpimpl.h"
#include "sockapi.h"

#define NA_SNMP_BAD_PARAMETER           1
#define NA_SNMP_OUT_OF_RESOURCES        2
#define NA_SNMP_INDEX_OUT_OF_RANGE      3
#define NA_SNMP_SET_FAILED              4
#define NA_SNMP_DELETE_FAILED           5
#define NA_SNMP_ALREADY_STARTED         6
#define NA_SNMP_AGENT_NOT_RUNNING       7
#define NA_SNMP_CLONE_NOT_FOUND         8
#define NA_SNMP_DUP_USER                9
#define NA_SNMP_MUST_SUPPLY_PRIV_KEY    10
#define NA_SNMP_MUST_SUPPLY_AUTH_KEY    11
#define NA_SNMP_DUPLICATE_COMMUNITY     12



/*ad*
 * Maximum value for snmpEngineBoots and snmpEngineTime as stated in
 * RFC-3411.
 *
 * @category SNMP:v3
 * @since 6.2
 *
 * @see @link naSnmpSetEngineBoots
 * @see @link naSnmpGetEngineInfo
*ad*/
#define NA_SNMP_MAX_BOOTS_TIME      (2147483647)


/*ad*
 * Minimum value for snmpEngineBoots as stated in
 * RFC-3411.
 *
 * @category SNMP:v3
 * @since 6.2
 * @external
 *
 * @see @link naSnmpSetEngineBoots
 * @see @link naSnmpGetEngineInfo
*ad*/
#define NA_SNMP_MIN_BOOTS           (1)


/*ad*
 * Bit field values for supported SNMP versions.  These values are passed
 * to @link naSnmpSetAllowedVersions and returned by
 * @link naSnmpGetAllowedVersions.
 *
 * @category SNMP:v3
 * @since 6.2
 * @external
 *
 * @name snmpVersions       "SNMP Version Constants"
 *
 * @param  NA_SNMP_VERSION_V1_ALLOWED   Set to indicate agent will communicate over SNMPv1.
 * @param  NA_SNMP_VERSION_V2c_ALLOWED  Set to indicate agent will communicate over SNMPv2c.
 * @param  NA_SNMP_VERSION_V3_ALLOWED   Set to indicate agent will communicate over SNMPv3.
 *
 * @see @link naSnmpSetAllowedVersions
 * @see @link naSnmpGetAllowedVersions
*ad*/
#define NA_SNMP_VERSION_V1_ALLOWED          (1)
#define NA_SNMP_VERSION_V2c_ALLOWED         (2)
#define NA_SNMP_VERSION_V3_ALLOWED          (4)


#ifdef IPV6_ENABLED
#define ENGINE_ID_LENGTH 21
#else
#define ENGINE_ID_LENGTH 9
#endif
/*ad*
 * Maximum length of an SNMP engine ID.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2 
 *
 * @see @link NaSnmpEngine_t
 * @see @link naSnmpGetEngineInfo
 * @see @link naSnmpSetEngineId
 * @see @link naSnmpSetDefaultEngineId
*ad*/
#define NA_SNMP_ENGINE_ID_LENGTH            (ENGINE_ID_LENGTH)



/*ad*
 * Maximum length of an SNMP USM name.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2 
 *
 * @see @link NaSnmpUsmEntry_t
 * @see @link NaSnmpVacmViewTreeFamilyEntry_t
 * @see @link NaSnmpVacmSecurityToGroupEntry_t
 * @see @link NaSnmpVacmAccessEntry_t
 * @see @link NaSnmpVacmContextEntry_t
 * @see @link NaSnmpCommunityTableEntry_t
 * @see @link naSnmpInsertVacmAccessEntry
 * @see @link naSnmpGetVacmAccessEntry
 * @see @link naSnmpDeleteVacmAccessEntry
 * @see @link naSnmpInsertS2GEntry
 * @see @link naSnmpDeleteS2GEntry
 * @see @link naSnmpInsertVtfEntry
 * @see @link naSnmpDeleteVtfEntry
 * @see @link naSnmpInsertUserEntry
 * @see @link naSnmpDeleteUserEntry
 * @see @link naSnmpCloneUserEntry
 *
*ad*/
#define NA_SNMP_USM_NAME_LENGTH             (32)


/*ad*
 * Maximum length of an SNMP USM password or key.
 *
 * @external
 * @category SNMP:v3
 * @since 7.3 
 *
 * @see @link NaSnmpUsmEntry_t
 * @see @link naSnmpInsertUserEntry
*ad*/
#define NA_SNMP_MAX_KEY_LENGTH       (40)

/*ad*
 * Maximum length of an SNMP object ID.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2 
 *
 * @see @link NaSnmpUsmEntry_t
 * @see @link NaSnmpVacmViewTreeFamilyEntry_t
*ad*/
#define NA_SNMP_MAX_OID_LENGTH              (MAX_NAME_LEN)



/*ad*
 * Maximum length of an VACM mask.  Each bit in the
 * mask corresponds to one component of an OID.  Since
 * an OID can have up to 128 components and there are
 * 8 bits to each octet, the max length is 128/8 or 16.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2 
 *
 * @see @link NaSnmpVacmViewTreeFamilyEntry_t
*ad*/
#define NA_SNMP_MAX_VACM_MASK_LENGTH        (16)


/*ad*
 * Enumerated type for SNMP authentication protocols as describedin RFC-3414.
 * Authentication protocols are used when exchanging authentication credentials
 * with SNMP consoles.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_NO_AUTH_PROTOCOL          No authentication protocol for this user.
 * @param NA_SNMP_HMACMD5_AUTH_PROTOCOL     The HMAC-MD5-96 Digest Authentication Protocol.
 * @param NA_SNMP_HMACSHA_AUTH_PROTOCOL     Not supported.
 *
 * @see @link NaSnmpUsmEntry_t
*ad*/
typedef enum
{
    NA_SNMP_NO_AUTH_PROTOCOL = 0,
    NA_SNMP_HMACMD5_AUTH_PROTOCOL,
    NA_SNMP_HMACSHA_AUTH_PROTOCOL
} NaSnmpAuthProtocol_t;



/*ad*
 * Enumerated type for SNMP privacy protocols as described in RFC-3414.  Privacy 
 * protocols are used after the connection has been established to encrypt requests
 * and responses.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_NO_PRIV_PROTOCOL          No privacy protocol for this user.
 * @param NA_SNMP_DES_PRIV_PROTOCOL         The CBC-DES Symmetric Encryption Protocol.
 *
 * @see @link NaSnmpUsmEntry_t
*ad*/
typedef enum
{
    NA_SNMP_NO_PRIV_PROTOCOL = 0,
    NA_SNMP_DES_PRIV_PROTOCOL
} NaSnmpPrivProtocol_t;


/*ad*
 * Enumerated type for SNMPv2 StorageType as defined in RFC-2579.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_OTHER         The RFC describes this value as "eh?"
 * @param NA_SNMP_VOLATILE      Entry will be lost when system is rebooted.
 * @param NA_SNMP_NONVOLATILE   Entry stored in NVRAM and will not be lost when system is rebooted.
 * @param NA_SNMP_PERMANENT     Entry is partially stored in ROM.
 * @param NA_SNMP_READONLY      Entry is completely stored in ROM.
 *
 * @note	Only NA_SNMP_VOLATILE is supported. All other storage types act as NA_SNMP_VOLATILE.
 *
 * @see @link NaSnmpUsmEntry_t 
 * @see @link NaSnmpVacmViewTreeFamilyEntry_t
 * @see @link NaSnmpVacmSecurityToGroupEntry_t
 * @see @link NaSnmpVacmAccessEntry_t
 * @see @link naSnmpCloneUserEntry
*ad*/
typedef enum
{
    NA_SNMP_OTHER = 1,
    NA_SNMP_VOLATILE = 2,
    NA_SNMP_NONVOLATILE = 3,
    NA_SNMP_PERMANENT = 4,
    NA_SNMP_READONLY = 5
} NaSnmpStorageType_t;


/*ad*
 * Enumerated type for SNMPv2 RowStatus as defined in RFC-2579.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_ROW_STATUS_NO_CHANGE          This value is used by the API to indicate 
 *                                              the row status should not be changed.
 * @param NA_SNMP_ROW_STATUS_ACTIVE             Entry has been activated.
 * @param NA_SNMP_ROW_STATUS_NOT_IN_SERVICE     Entry exists, but is not available for use.
 * @param NA_SNMP_ROW_STATUS_NOT_READY          Entry exists, but is incomplete.
 * @param NA_SNMP_ROW_STATUS_CREATE_AND_GO      Specified to create an entry and have its status set to active.
 * @param NA_SNMP_ROW_STATUS_CREATE_AND_WAIT    Specified to create an entry, but not activate it.
 * @param NA_SNMP_ROW_STATUS_DESTROY            Specified to destroy an entry.
 *
 * @see @link NaSnmpUsmEntry_t
 * @see @link naSnmpCloneUserEntry
*ad*/
typedef enum
{
    NA_SNMP_ROW_STATUS_NO_CHANGE = 0,
    NA_SNMP_ROW_STATUS_ACTIVE = 1,
    NA_SNMP_ROW_STATUS_NOT_IN_SERVICE = 2,
    NA_SNMP_ROW_STATUS_NOT_READY = 3,
    NA_SNMP_ROW_STATUS_CREATE_AND_GO = 4,
    NA_SNMP_ROW_STATUS_CREATE_AND_WAIT = 5,
    NA_SNMP_ROW_STATUS_DESTROY = 5
} NaSnmpRowStatusType_t;




/*ad*
 * Enumerated type for possible values of the vacmViewTreeFamilyType columnar 
 * object defined in RFC-3415.  The value of the object determines whether the
 * VACM entry is excluding or including a subtree in a view.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_VACM_INCLUDED subtree defined by this entry should be included in the view.
 * @param NA_SNMP_VACM_EXCLUDED subtree defined by this entry should be excluded from the view.
 *
 * @see @link NaSnmpVacmViewTreeFamilyEntry_t
*ad*/
typedef enum
{
    NA_SNMP_VACM_INCLUDED = 1,
    NA_SNMP_VACM_EXCLUDED = 2
} NaSnmpVacmViewTreeFamilyType_t;


/*ad*
 * Enumerated type for possible values of the securityModel type defined
 * in RFC-3411.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_VACM_SECURITY_MODEL_ANY       Any security model.  This value is illegal most of the time.
 * @param NA_SNMP_VACM_SECURITY_MODEL_SNMPv1    SNMPv1 level security, which means none.
 * @param NA_SNMP_VACM_SECURITY_MODEL_SNMPv2c   SNMPv2c level security.
 * @param NA_SNMP_VACM_SECURITY_MODEL_USM       User-Based Security Model.
 *
 * @see @link NaSnmpVacmSecurityToGroupEntry_t
 * @see @link NaSnmpVacmAccessEntry_t
*ad*/
typedef enum
{
    NA_SNMP_VACM_SECURITY_MODEL_ANY = 0,
    NA_SNMP_VACM_SECURITY_MODEL_SNMPv1 = 1,
    NA_SNMP_VACM_SECURITY_MODEL_SNMPv2c = 2,
    NA_SNMP_VACM_SECURITY_MODEL_USM = 3
} NaSnmpSecurityModel_t;



/*ad*
 * Enumerated type for possible values of the securityLevel type defined
 * in RFC-3411.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_VACM_SECURITY_LEVEL_NO_AUTH_NO_PRIV   No authentication and no privacy.
 * @param NA_SNMP_VACM_SECURITY_LEVEL_AUTH_NO_PRIV      Requests are authenticated, but there is no privacy.
 * @param NA_SNMP_VACM_SECURITY_LEVEL_AUTH_PRIV         Requesta are authenticated, and a privacy protocol is used.
 *
 * @see @link NaSnmpVacmAccessEntry_t
*ad*/
typedef enum
{
    NA_SNMP_VACM_SECURITY_LEVEL_NO_AUTH_NO_PRIV = 1,
    NA_SNMP_VACM_SECURITY_LEVEL_AUTH_NO_PRIV = 2,
    NA_SNMP_VACM_SECURITY_LEVEL_AUTH_PRIV = 3
} NaSnmpSecurityLevel_t;



/*ad*
 * Enumerated type for possible values of the contextMatch object defined
 * in RFC-3415.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param NA_SNMP_VACM_ACCESS_CONTEXT_MATCH_EXACT       Must match context prefix and name exactly.
 * @param NA_SNMP_VACM_ACCESS_CONTEXT_MATCH_PREFIX      Only need to match prefix exactly.
 *
 * @see @link NaSnmpVacmAccessEntry_t
*ad*/
typedef enum
{
    NA_SNMP_VACM_ACCESS_CONTEXT_MATCH_EXACT = 1,
    NA_SNMP_VACM_ACCESS_CONTEXT_MATCH_PREFIX = 2
} NaSnmpAccessContextMatch_t;


/*ad*
 * This structure is used by @link naSnmpGetEngineInfo to 
 * pass configuration settings.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param id            Unique identifier for the SNMP engine assigned by the administrator.
 * @param boots         Number of times system has rebooted.
 * @param time          Amount of time in seconds system has been up since last reboot.
 * @param maxMessageSize    Reserved.  Set to zero.
 *
 * @see @link naSnmpGetEngineInfo
 * @see @link naSnmpSetEngineBoots 
 * @see @link naSnmpSetEngineId
*ad*/
typedef struct
{
    BYTE id[NA_SNMP_ENGINE_ID_LENGTH];
    WORD32 boots;
    WORD32 time;
    WORD32 maxMessageSize;
} NaSnmpEngine_t;



/*ad*
 * This structure is used by @link naSnmpInsertUserEntry, @link naSnmpGetUserEntry,
 * @link naSnmpDeleteUserEntry, and naSnmpUserEntryChanged_t callback to pass USM entries.
 *
 * The USM table is indexed by the engineId and name fields.
 *
 * This structure implements the UsmUserEntry SEQUENCE described in RFC3414.
 * 
 *
 * @external
 * @category SNMP:v3
 * @since 7.3
 *
 * @param name          Name of the user.  This field and the engineId are combined
 *                      to form a table index.
 * @param nameLength    Length of name in bytes.
 * @param securityName  Should be set to the same value as name.
 * @param securityNameLength    Number of bytes in securityName.
 * @param cloneFrom     Name of USM entry to clone this one from.
 * @param cloneFromLength       Number of bytes in cloneFrom.
 * @param authProtocol  Protocol used for authentication.
 * @param authPassword  The user authentication password, which is converted to the secret 
 *						authentication key in the @link naSnmpInsertUserEntry function. 
 *						The secret authentication key is used for messages sent on behalf
 *                      of this user to/from the SNMP engine identified by engineID.
 *						This field is used by @link naSnmpInsertUserEntry
 *						to add a user with the known password. Only one of authPassword and 
 *						authKey could be used at a time.
 * @param authPasswordLength	Length of the authentication password in bytes.
 * @param authKey		The user secret authentication key, which is used for messages sent 
 *						on behalf of this user to/from the SNMP engine identified by engineID.
 *						This field is returned in an entry by @link naSnmpGetUserEntry
 *						or @link naSnmpUserEntryChanged_t callback. It can then be used by 
 *						@link naSnmpInsertUserEntry to add a user after the system is rebooted.
 *						Only one of authPassword and authKey could be used at a time.
 * @param authKeyLength	Length of the authentication key in bytes; this value is returned 
 *                      by @link naSnmpGetUserEntry or @link naSnmpUserEntryChanged_t callback. 
 * @param privProtocol  Protocol used for privacy.
 * @param privPassword  The user privacy password, which is converted to the secret 
 *						privacy key in the @link naSnmpInsertUserEntry function. 
 *						The secret privacy key is used for messages sent on behalf
 *                      of this user to/from the SNMP engine identified by engineID.
 *						This field is used by @link naSnmpInsertUserEntry
 *						to add a user with the known password. Only one of privPassword and 
 *						privKey could be used at a time.
 * @param privPasswordLength   Length of the privacy password in bytes.
 * @param privKey		The user secret privacy key, which is used for messages sent 
 *						on behalf of this user to/from the SNMP engine identified by engineID.
 *						This field is returned in an entry by @link naSnmpGetUserEntry
 *						or @link naSnmpUserEntryChanged_t callback. It can then be used by 
 *						@link naSnmpInsertUserEntry to add a user after the system is rebooted.
 *						Only one of privPassword and privKey could be used at a time.
 * @param privKeyLength	Length of the privacy key in bytes; this value is returned by @link
 *                      naSnmpGetUserEntry or @link naSnmpUserEntryChanged_t callback. 
 * @param publicValue   A publicly-readable value which can be written as part
 *                      of the procedure for changing a user's secret
 *                      authentication and/or privacy key, and later read to
 *                      determine whether the change of the secret was
 *                      effected.  The idea is that the keys can be written,
 *                      but not read, so there is no direct way of determining
 *                      if a write to them succeeded.  So, a console can write
 *                      to this field when it changes the keys, and then read
 *                      back this field to verify the write occurred.
 * @param publicValueLength Length of publicValue in bytes.
 * @param storageType   Indicates whether this entry will be preserved when 
 *                      the system is powered down or rebooted.
 * @param userStatus    Current status of the entry.
 *
 *
 * @see @link naSnmpInsertUserEntry
 * @see @link naSnmpGetUserEntry
 * @see @link naSnmpDeleteUserEntry
 * @see @link naSnmpCloneUserEntry
 * @see @link naSnmpUserEntryChanged_t
*ad*/
typedef struct NaSnmpUsmUserEntry_t
{
    char name[NA_SNMP_USM_NAME_LENGTH];
    unsigned nameLength;
    char securityName[NA_SNMP_USM_NAME_LENGTH];
    unsigned securityNameLength;
    oid cloneFrom[NA_SNMP_MAX_OID_LENGTH];
    unsigned cloneFromLength;
    NaSnmpAuthProtocol_t authProtocol;
    char authPassword[NA_SNMP_MAX_KEY_LENGTH];
    unsigned authPasswordLength;
    BYTE authKey[NA_SNMP_MAX_KEY_LENGTH];
    unsigned authKeyLength;
    NaSnmpPrivProtocol_t privProtocol;
    BYTE privPassword[NA_SNMP_MAX_KEY_LENGTH];
    unsigned privPasswordLength;
    BYTE privKey[NA_SNMP_MAX_KEY_LENGTH];
    unsigned privKeyLength;
    BYTE publicValue[NA_SNMP_USM_NAME_LENGTH];
    unsigned publicValueLength;
    NaSnmpStorageType_t storageType;
    NaSnmpRowStatusType_t userStatus;
} NaSnmpUsmEntry_t;



/*ad*
 * This structure is used by @link naSnmpInsertVtfEntry, @link naSnmpGetVtfEntry,
 * and @link naSnmpDeleteVtfEntry to pass VACM view tree family entries.  The
 * structure holds information on a particular family of view subtrees included 
 * in or excluded from a particular SNMP context's MIB view.
 *
 * The table is indexed by the name and subtree fields.
 *
 * This structure implements the VacmViewTreeFamilyEntry SEQUENCE described in
 * RFC-3415.
 * 
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param name          The human readable name for a family of view subtrees.
 * @param nameLength    Length of name in bytes.
 * @param subtree       The MIB subtree which when combined with the
 *                      mask field defines a family of view subtrees.
 * @param subtreeLength Length of subtree.
 * @param mask          The bit mask which, in combination with the
 *                      corresponding instance of vacmViewTreeFamilySubtree,
 *                      defines a family of view subtrees.  See RFC-3415
 *                      for details.
 * @param maskLength    Length of mask in bytes.
 * @param type          Indicates whether we are defining a view of subtrees
 *                      which is included or excluded from the MIB view.
 * @param storageType   The storage type for this conceptual row.
 *                      Conceptual rows having the value 'permanent' need not
 *                      allow write-access to any columnar objects in the row.
 *
 * @see @link naSnmpInsertVtfEntry
 * @see @link naSnmpGetVtfEntry
 * @see @link naSnmpDeleteVtfEntry
*ad*/
typedef struct 
{
    char name[NA_SNMP_USM_NAME_LENGTH];
    unsigned nameLength;
    oid subtree[NA_SNMP_MAX_OID_LENGTH];
    unsigned subtreeLength;
    BYTE mask[NA_SNMP_MAX_VACM_MASK_LENGTH];
    unsigned maskLength;
    NaSnmpVacmViewTreeFamilyType_t type;
    NaSnmpStorageType_t storageType;
} NaSnmpVacmViewTreeFamilyEntry_t;



/*ad*
 * This structure is used by @link naSnmpInsertS2GEntry, @link naSnmpGetS2GEntry,
 * and @link naSnmpDeleteS2GEntry to pass VACM Security-to-group (S2G) entries.  The
 * structure holds information on a particular family of view subtrees included 
 * in or excluded from a particular SNMP context's MIB view.
 *
 * The table is indexed by the securityModel and securityName fields.
 * 
 * This structure implements the VacmSecurityToGroupEntry SEQUENCE described
 * in RFC-3415.
 *
 * @external
 * @category SNMP:v3
 * @since 6.2
 *
 * @param securityModel The SNMP security model used by this entry.  The value
 *                      NA_SNMP_VACM_SECURITY_MODEL_ANY(0) is not valid.
 * @param securityName  The securityName for the principal, represented in a
 *                      Security Model independent format, which is mapped by
 *                      this entry to a groupName.
 * @param securityNameLength    Length of securityName in bytes.
 * @param groupName     The name of the group to which this entry (e.g., the
 *                      combination of securityModel and securityName)
 *                      belongs.  This groupName is used as index into the
 *                      vacmAccessTable to select an access control policy.
 *                      However, a value in this table does not imply that an
 *                      instance with the value exists in table vacmAccesTable.
 * @param groupNameLength   Length of groupName in bytes.
 * @param storageType   Storage type for this entry.
 *
 * @see @link naSnmpInsertS2GEntry
 * @see @link naSnmpGetS2GEntry
 * @see @link naSnmpDeleteS2GEntry
*ad*/
typedef struct
{
    NaSnmpSecurityModel_t securityModel;
    char securityName[NA_SNMP_USM_NAME_LENGTH];
    unsigned securityNameLength;
    char groupName[NA_SNMP_USM_NAME_LENGTH];
    unsigned groupNameLength;
    NaSnmpStorageType_t storageType;
} NaSnmpVacmSecurityToGroupEntry_t;



/*ad*
 * This structure is used by @link naSnmpInsertVacmAccessEntry, @link naSnmpGetVacmAccessEntry,
 * and @link naSnmpDeleteVacmAccessEntry to pass VACM entries.  The
 * structure holds information on a particular family of view subtrees included 
 * in or excluded from a particular SNMP context's MIB view.
 *
 * The table is indexed by a groupName, a contextPrefix, a securityModel and a securityLevel.  
 * The groupName comes from the @link NaSnmpVacmSecurityToGroupEntry_t entry this entry
 * is tied to.
 *
 * This structure implements the VacmAccessEntry SEQUENCE described in RFC-3415.
 * 
 *
 * @external
 * @category SNMP:v3
 * @since 7.0
 *
 * @param groupName         VACM group name.
 * @param groupNameLength   Group name length in bytes. 
 *
 * @param contextPrefix     In order to gain the access rights allowed by this
 *                          conceptual row, a contextName must match exactly
 *                          (if the value of vacmAccessContextMatch is 'exact')
 *                          or partially (if the value of vacmAccessContextMatch
 *                          is 'prefix') to the value of the instance of this
 *                          object.
 * @param contextPrefixLength   Length of the contextPrefix in bytes.
 * @param securityModel     The SNMP security model used by this entry.  The value
 *                          NA_SNMP_VACM_SECURITY_MODEL_ANY(0) is not valid.
 * @param securityLevel     The minimum level of security required in order to
 *                          gain the access rights allowed by this conceptual
 *                          row.  
 * @param contextMatch      Determines whether an exact match of the prefix and
 *                          contextName are required, or just the prefix.
 * @param readView          The value of an instance of this object identifies
 *                          the MIB view of the SNMP context to which this
 *                          conceptual row authorizes read access.
 * @param readViewLength    Length of readView in bytes.
 * @param writeView         The value of an instance of this object identifies
 *                          the MIB view of the SNMP context to which this
 *                          conceptual row authorizes write access.
 * @param writeViewLength   Length of writeView in bytes.
 * @param notifyView        The value of an instance of this object identifies
 *                          the MIB view of the SNMP context to which this
 *                          conceptual row authorizes access for notifications.
 * @param notifyViewLength  Length of notifyView in bytes.
 * @param storageType       Storage type for this entry.
 *
 * @see @link naSnmpInsertVacmAccessEntry
 * @see @link naSnmpGetVacmAccessEntry
 * @see @link naSnmpDeleteVacmAccessEntry
*ad*/
typedef struct
{
    BYTE groupName[NA_SNMP_USM_NAME_LENGTH];
    unsigned groupNameLength;
    BYTE contextPrefix[NA_SNMP_USM_NAME_LENGTH];
    unsigned contextPrefixLength;
    NaSnmpSecurityModel_t securityModel;
    NaSnmpSecurityLevel_t securityLevel;
    NaSnmpAccessContextMatch_t contextMatch;
    BYTE readView[NA_SNMP_USM_NAME_LENGTH];
    unsigned readViewLength;
    BYTE writeView[NA_SNMP_USM_NAME_LENGTH];
    unsigned writeViewLength;
    BYTE notifyView[NA_SNMP_USM_NAME_LENGTH];
    unsigned notifyViewLength;
    NaSnmpStorageType_t storageType;
} NaSnmpVacmAccessEntry_t;

/*ad*
 * Local context table entry data type.
 *
 * This structure implements the VacmContextEntry SEQUENCE described in RFC-2575.
 *
 * @external
 * @category SNMP:v3
 * @since 7.0
 *
 *
 * @param contextName		    Locally available context btween 0 and 32 bytes long.      
 * @param contextNameLen        Length of the context in bytes.
 *
 * @see @link naSnmpInsertContextEntry
 * @see @link naSnmpGetContextEntry
 * @see @link naSnmpDeleteContextEntry
*ad*/
typedef struct
{
    int contextNameLen;
    char contextName[NA_SNMP_USM_NAME_LENGTH];

} NaSnmpVacmContextEntry_t;


/*ad*
 * Local community data
 *
 * The community table (RFC-2576) is part of the SNMPv3 framework and provides a way to define 
 * a SNMP v1/v2c community and map it to a SNMPv3 USM user. The same access rights that apply to 
 * the V3 user apply to the community.
 *
 * @external
 * @category SNMP:v3
 * @since 7.0
 *
 *
 * @param communityIndex                The unique index value of a row in the community table.      
 * @param communityName                 Community name
 * @param communitySecurityName         Corresponding value of communityName in a Security Model
 *                                      independent format
 * @param communityContextEngineID      Indicates the location of the context in which management 
 *                                      information is accessed when using the communityName.
 * @param communityContextName          The context in which management information is accessed 
 *                                      when using the communityName
 * @param communityTransportTag         A set of transport endpoints from which to accept authenticatedmanagement 
 *                                      requests.The transports are specified in the snmpTargetAddrTable,
 *                                      that is initialized using @link NaSnmpNotificationTarget_t structure. 
 * @param communityIndexLen             Length of communityIndex in bytes.
 * @param communityNameLen              Length of communityName in bytes.
 * @param communitySecurityNameLen      Length of communitySecurityName in bytes.
 * @param communityContextEngineIDLen   Length of communityContextEngineID in bytes.
 * @param communityContextNameLen       Length of communityContextName in bytes.
 * @param communityTransportTagLen      Length of communityTransportTag in bytes.
 * @param communityStorageType          Storage type for this entry.
 *
 * @see @link naSnmpInsertCommunityTableEntry
 * @see @link naSnmpDeleteCommunityTableEntry
 *
*ad*/
typedef struct
{
    BYTE communityIndex[NA_SNMP_USM_NAME_LENGTH];
    BYTE communityName[NA_SNMP_USM_NAME_LENGTH];
    BYTE communitySecurityName[NA_SNMP_USM_NAME_LENGTH];
    BYTE communityContextEngineID[NA_SNMP_USM_NAME_LENGTH];
    BYTE communityContextName[NA_SNMP_USM_NAME_LENGTH];
    BYTE communityTransportTag[NA_SNMP_USM_NAME_LENGTH];
    BYTE communityIndexLen;
    BYTE communityNameLen;
    BYTE communitySecurityNameLen;
    BYTE communityContextEngineIDLen;
    BYTE communityContextNameLen;
    BYTE communityTransportTagLen;
    BYTE communityStorageType;
} NaSnmpCommunityTableEntry_t;


/*ad*
 * Enumerated type of local values for SnmpTargetParamsMPModel, used to initialize the
 * Target MIB, RFC-3413.
 *
 * @external
 * @category SNMP:v3
 * @since 7.1
 *
 * @param NA_SNMP_MPMODEL_V1        SNMPv1 message processing model.
 * @param NA_SNMP_MPMODEL_V2C       SNMPv2c message processing model.
 * @param NA_SNMP_MPMODEL_V3        SNMPv3 message processing model.
 *
 * @see @link NaSnmpNotificationTarget_t
*ad*/
typedef enum
{
    NA_SNMP_MPMODEL_V1  = 1,
    NA_SNMP_MPMODEL_V2C = 2,
    NA_SNMP_MPMODEL_V3  = 3

} NaSnmpTargetParamsMPModel_t;


/*ad*
 * This structure is used to initialize notification targets in Notification MIB and 
 * Target AddressMIB, (RFC-2573, RFC-3413) by calling @link naSnmpSetNotificationTargets function.
 *
 * @external
 * @category SNMP:v3
 * @since 7.1
 *
 * @param destAddr          Pointer to a NULL-terminated string of the IPv4 or IPv6 address of 
 *                          the trap target in presentation format. 
 * @param destPort          Port number of the trap target.
 * @param addrFamily        AF_INET or AF_INET6.
 * @param securityName      "public" or "private"
 * @param mpModel           Message processing model, specifying SNMP version of trap -
 *                          NA_SNMP_MPMODEL_V1, NA_SNMP_MPMODEL_V2C, or NA_SNMP_MPMODEL_V3.
 *
 * @see @link naSnmpSetNotificationTargets
 *
*ad*/
typedef struct
{
    char          * destAddr;
    unsigned short  destPort;
    unsigned        addrFamily;
    char          * securityName;
    NaSnmpTargetParamsMPModel_t   mpModel;

} NaSnmpNotificationTarget_t;


/*ad*
 * A prototype of a callback function, used when a USM entry has been added, modified,
 * or deleted remotely.
 *
 * @external
 * @category SNMP:v3
 * @since 7.3
 *
 *
 * @param entry		     Pointer to @link NaSnmpUsmEntry_t structure for an added, modified,
 *						 or deleted user.
 * @param deleted        TRUE if this user has been deleted, FALSE otherwise.
 *
 * @see @link naSnmpRegisterUserChangedCallback
*ad*/
typedef void (* naSnmpUserEntryChanged_t)(const NaSnmpUsmEntry_t * entry, BOOLEAN deleted);

/*ad*
 * A prototype of a callback function, used when a VACM Security-to-group (S2G) entry has been 
 * added, modified, or deleted remotely.
 *
 * @external
 * @category SNMP:v3
 * @since 7.3
 *
 * @param entry		     Pointer to @link NaSnmpVacmSecurityToGroupEntry_t structure for an added, 
 *						 modified, or deleted VACM S2G entry.
 * @param deleted        TRUE if this user has been deleted, FALSE otherwise.
 *
 * @see @link naSnmpRegisterVacmS2GChangedCallback
*ad*/
typedef void (* naSnmpVacmS2GEntryChanged_t)(const NaSnmpVacmSecurityToGroupEntry_t * entry, BOOLEAN deleted);

/*ad*
 * A prototype of a callback function, used when a VACM Access entry has been added, modified, 
 * or deleted remotely.
 *
 * @external
 * @category SNMP:v3
 * @since 7.3
 *
 * @param entry		     Pointer to @link NaSnmpVacmAccessEntry_t structure for an added, 
 *						 modified, or deleted VACM Access entry.
 * @param deleted        TRUE if this user has been deleted, FALSE otherwise.
 *
 * @see @link naSnmpRegisterVacmAccessChangedCallback
*ad*/
typedef void (* naSnmpVacmAccessEntryChanged_t)(const NaSnmpVacmAccessEntry_t * entry, BOOLEAN deleted);

/*ad*
 * A prototype of a callback function, used when a VACM View Family Tree (VTF) entry has been added, 
 * modified, or deleted remotely.
 *
 * @external
 * @category SNMP:v3
 * @since 7.3
 *
 * @param entry		     Pointer to @link NaSnmpVacmViewTreeFamilyEntry_t structure for 
 *						 an added, modified, or deleted VACM VTF entry.
 * @param deleted        TRUE if this user has been deleted, FALSE otherwise.
 *
 * @see @link naSnmpRegisterVacmVtfChangedCallback
*ad*/
typedef void (* naSnmpVacmVtfEntryChanged_t)(const NaSnmpVacmViewTreeFamilyEntry_t * entry, BOOLEAN deleted);

void naSnmpRegisterUserChangedCallback(naSnmpUserEntryChanged_t fn);
void naSnmpRegisterVacmS2GChangedCallback(naSnmpVacmS2GEntryChanged_t fn);
void naSnmpRegisterVacmAccessChangedCallback(naSnmpVacmAccessEntryChanged_t fn);
void naSnmpRegisterVacmVtfChangedCallback(naSnmpVacmVtfEntryChanged_t fn);


NaStatus naSnmpSetNotificationTargets(NaSnmpNotificationTarget_t * const trapTarget, unsigned numTargets);
NaStatus naSetNotificationUserName(const char * trap_user_name);
NaStatus naSetNotificationContextName(const char * trap_context_name);
NaStatus naSnmpInsertCommunityTableEntry(NaSnmpCommunityTableEntry_t * const entry);
NaStatus naSnmpDeleteCommunityTableEntry(char * comIndex);
NaStatus naSnmpInsertVacmAccessEntry(NaSnmpVacmAccessEntry_t * const entry);
NaStatus naSnmpGetVacmAccessEntry(unsigned listIndex, NaSnmpVacmAccessEntry_t * entry);
NaStatus naSnmpDeleteVacmAccessEntry(NaSnmpVacmAccessEntry_t * const entry);
NaStatus naSnmpInsertS2GEntry(NaSnmpVacmSecurityToGroupEntry_t * const entry);
NaStatus naSnmpGetS2GEntry(unsigned listIndex, NaSnmpVacmSecurityToGroupEntry_t *entry);
NaStatus naSnmpDeleteS2GEntry(NaSnmpVacmSecurityToGroupEntry_t * const entry);
NaStatus naSnmpInsertVtfEntry(NaSnmpVacmViewTreeFamilyEntry_t * const vtf_entry);
NaStatus naSnmpGetVtfEntry(unsigned listIndex, NaSnmpVacmViewTreeFamilyEntry_t * vtf_entry);
NaStatus naSnmpDeleteVtfEntry(NaSnmpVacmViewTreeFamilyEntry_t * const vtf_entry);
NaStatus naSnmpInsertUserEntry(NaSnmpUsmEntry_t * const userEntry);
NaStatus naSnmpCloneUserEntry(BYTE *cloneFrom, unsigned cloneFromLength, 
                              BYTE *username, unsigned usernameLength,
                              NaSnmpStorageType_t storageType,
                              NaSnmpRowStatusType_t status);
NaStatus naSnmpGetUserEntry(unsigned listIndex, NaSnmpUsmEntry_t * userEntry);
NaStatus naSnmpDeleteUserEntry(BYTE *name, int nameLen);
NaStatus naSnmpGetEngineInfo(BYTE *id, unsigned *idLength, unsigned *boots, unsigned *time);
NaStatus naSnmpSetEngineId(BYTE * const id, int length);
NaStatus naSnmpSetDefaultEngineId(const struct sockaddr_storage * srcAddr);
NaStatus naSnmpSetEngineBoots(int boots);
NaStatus naSnmpSetAllowedVersions(WORD32 versionMask);
NaStatus naSnmpGetAllowedVersions(WORD32 * versionMask);
NaStatus naSnmpInsertContextEntry(NaSnmpVacmContextEntry_t * const entry);
NaStatus naSnmpGetContextEntry(unsigned indexNumber, NaSnmpVacmContextEntry_t * const entry);
NaStatus naSnmpDeleteContextEntry(NaSnmpVacmContextEntry_t * const entry);
NaStatus naSnmpSetAuthPassword(char * userName, char * password);
NaStatus naSnmpSetPrivPassword(char * userName, char * password);
NaStatus naSnmpSendNotifications(int generic_trap, 
                                 int specific_trap, 
                                 int interface_index,
                                 oid enterpriseNumber,
                                 int enterpriseLength,
                                 int num_variables, 
                                 struct variable_t const * variables);


#ifdef __cplusplus
}
#endif

#endif
