#

# Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

#

# U.S. Government Rights - Commercial software. Government users are subject

# to the Sun Microsystems, Inc. standard license agreement and applicable

# provisions of the FAR and its supplements.

#

#

# This distribution may include materials developed by third parties. Sun,

# Sun Microsystems, the Sun logo and Solaris are trademarks or registered

# trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

#

#

List of Entity MIB APIs

-----------------------

Physical Table (entPhysicalTable)

---------------------------------

extern int allocPhysicalEntry(int physidx, entPhysicalEntry_t *newPhysEntry);

  - Allocates an entry in the Physical Table. The physidx parameter

    is the physical index requested. If physidx = 0, it will try to use

    the first available index in the table.  If physidx > 0, then it will try

    to use the slot indicated by the index.

    The API returns a physical index alloted to the entry, and this may or may

    not be the same as the requested physical index.

    The memory associated with newPhysEntry can be freed. The API creates an

    internal copy of the data.

    Returns:

    - the index allocated to the physical entry

    - -1 for error in adding the entry

    Check the log for more details.

    NOTE: The physidx (other than 0) is not used in this release of the API,

          this is present for future purposes.

entPhysicalEntry_t *getPhysicalTableEntry(int index);

  - This API returns the actual Physical Table entry for the

    particular index. The caller must NOT change the values or release

    the memory of the entry that is returned.

    Returns:

    - the entry for that index

    - NULL on error in finding the entry or if the entry is stale

extern int deletePhysicalTableEntry(int xPhysicalIndex);

  - Delete the Physical Table entry associated with the xPhysicalIndex. The

    instances of xPhysicalIndex in the Alias Mapping Table, LP Mapping Table

    and the Physical Contains Table will also be deleted to maintain

    integrity among the various Entity MIB tables.

    Returns:

    - 0 for success

    - -1 if the xPhysicalIndex is not found

    - -2 if a stale entry was found for xPhysicalIndex.

extern int makePhysicalTableEntryStale(int xPhysicalIndex);

  - Makes the Physical Table entry associated with the xPhysicalIndex stale. 

    Stale means that the entry details are present in the agent's memory but

    it will not be displayed during any SNMP operation. The entry can be

    made available again with the call to the makePhysicalTableEntryLive

    API.

    The index allocated to a stale entry will not be allocated to another

    entry.

    The instances of xPhysicalIndex in the Alias Mapping Table, LP Mapping

    Table and the Physical Contains Table will be deleted to maintain

    integrity among the various Entity MIB tables.

    Returns:

    - 0 for success

    - -1 if the xPhysicalIndex is not found

    - -2 if a stale entry already exists for xPhysicalIndex.

extern int makePhysicalTableEntryLive(int xPhysicalIndex);

  - Makes the stale Physical Table entry associated with the xPhysicalIndex 

    live.

    Live means that the entry details that are present in the agent's memory 

    will be displayed during SNMP operations. The entry can be

    made stale with the call to the makePhysicalTableEntryStale API.

    Returns:

    - 0 for success

    - -1 if the xPhysicalIndex is not found

    - -2 if a live entry already exists for xPhysicalIndex.

entPhysicalEntry_t *getPhysicalStaleEntry(int index);

  - This API returns the stale Physical Table entry for the

    particular index. The caller must NOT change the values or release

    the memory of the entry that is returned.

    Returns:

    - the stale entry for that index

    - NULL on error in finding the entry or if a live entry exists.

int *getAllChildrenFromPhysicalContainedIn(int parentIndex);

  - Get the indexes for all the children in the Physical Table which has

    parentIndex as their parent (in the entPhysicalContainedIn field).

    Returns:

    - returns an array of indexes (integers) with null termination

    - NULL if no children, or invalid index, or not enough memory when

      allocating the array

    NOTE: The array is a copy and SHOULD be freed when done

Logical Table (entLogicalTable)

-------------------------------

extern int allocLogicalEntry(int logidx, entLogicalEntry_t * xnewLogicalEntry);

  - Allocates an entry in the Logical Table. The logidx parameter

    is the logical index requested. If logidx = 0, it will try to use

    the first available index in the table.  If physidx > 0, then it will try

    to use the slot indicated by the index.

    The API returns a logical index alloted to the entry, and this may or may

    not be the same as the requested logical index.

    The memory associated with xnewLogicalEntry can be freed. The API creates

    an internal copy of the data.

    Returns:

    - the index allocated to the logical entry

    - -1 for error in adding the entry

    Check the log for more details.

    NOTE: The logidx (other than 0) is not used in this release of the API,

          this is present for future purposes.

entLogicalEntry_t* getLogicalTableEntry(int xLogicalIndex);

  - This API returns the actual Logical Table entry for the

    particular index. The caller must NOT change the values or release

    the memory of the entry that is returned.

    Returns:

    - the entry for that index

    - NULL on error in finding the entry or if a stale entry exists.

extern int deleteLogicalTableEntry(int xLogicalIndex);

  - Delete the Logical Table entry associated with the xLogicalIndex. The

    instances of xLogicalIndex in the Alias Mapping Table, and the 

    LP Mapping Table will also be deleted to maintain integrity among the 

    various Entity MIB tables.

    Returns:

    - 0 for success

    - -1 if the xLogicalIndex is not found

    - -2 if a stale entry was found for xLogicalIndex.

extern int makeLogicalTableEntryStale(int xLogicalIndex);

  - Makes the Logical Table entry associated with the xLogicalIndex stale.

    Stale means that the entry details are present in the agent's memory but

    it will not be displayed during any SNMP operation. The entry can be

    made available again with the call to the makeLogicalTableEntryLive API.

    The index allocated to a stale entry will not be allocated to another

    entry.

    The instances of xLogicalIndex in the Alias Mapping Table, and the 

    LP Mapping Table will be deleted to maintain integrity among the various 

    Entity MIB tables.

    Returns:

    - 0 for success

    - -1 if the xPhysicalIndex is not found

    - -2 if a stale entry already exists for xPhysicalIndex.

extern int makeLogicalTableEntryLive(int xLogicalIndex);

  - Makes the stale Logical Table entry associated with the xLogicalIndex

    live.

    Live means that the entry details that are present in the agent's memory

    will be displayed during SNMP operations. The entry can be

    made stale with the call to the makeLogicalTableEntryStale API.

    Returns:

    - 0 for success

    - -1 if the xLogicalIndex is not found

    - -2 if a live entry already exists for xLogicalIndex.

entLogicalEntry_t *getLogicalStaleEntry(int index);

  - This API returns the stale Logical Table entry for the

    particular index. The caller must NOT change the values or release

    the memory of the entry that is returned.

    Returns:

    - the stale entry for that index

    - NULL on error in finding the entry or if a live entry exists.

LP Mapping Table (entLPMappingTable)

------------------------------------

extern int addLPMappingTableEntry(int xentLogicalIndex, int xentPhysicalIndex);

  - Adds an entry to the LP Mapping Table with the xentLogicalIndex as the

    primary index and xentPhysicalIndex as the secondary index.

    Returns:

    - 0 for successful addition

    - 1 if the entry for the given xentPhysicalIndex and

      xentLogicalIndex already exists.

    - -1 for failure

extern int deleteLPMappingTableEntry(int xLogicalIndex, int xPhysicalIndex);

  - Deletes the entry of the LP Mapping Table with the xLogicalIndex as 

    the primary index and xPhysicalIndex as the secondary index.

    Returns:

    - 0 for successful deletion

    - -1 for failure

    - -2 for stale entry (either logical or physical index, or both)

extern int deleteLPMappingLogicalIndex(int xentLogicalIndex);

  - Deletes all the entries of the LP Mapping Table with the xentLogicalIndex

    as the primary index.

    Returns:

    - number of deleted entries for successful deletion

    - -1 for failure

    - -2 for stale logical entry

extern int deleteLPMappingPhysicalIndex(int xentPhysicalIndex);

  - Deletes all the entries of the LP Mapping Table with the xentPhysicalIndex

    as the secondary index.

    Returns:

    - number of deleted entries for successful deletion

    - -1 if no entry was deleted.

    - -2 for stale physical entry

Alias Mapping Table (entAliasMappingTable)

------------------------------------------

extern int addAliasMappingTableEntry(int xentPhysicalIndex, int xentLogicalIndex, oid* xAliasMapId, int xAliasMapIdSize);

  - Adds an entry to the Alias Mapping Table with xentPhysicalIndex as 

    the primary index and xentLogicalIndex as the secondary index.

    xAliasMapId is the alias (OID) for the entry and xAliasMapIdSize is a size

    in bytes of xAliasMapId

    Returns:

    - 0 for successful addition

    - 1 if the entry already exists for the given xentPhysicalIndex and

      xentLogicalIndex already exists.

    - -1 for failure

extern int deleteAliasMappingTableEntry(int xentPhysicalIndex, int xentLogicalIndex);

  - Deletes the entry of the Alias Mapping Table with xentPhysicalIndex as

    the primary index and xentLogicalIndex as the secondary index.

    Returns:

    - 0 for successful deletion

    - -1 for entry not found

    - -2 for stale entry

extern int deleteAliasMappingLogicalIndex(int xentLogicalIndex);

  - Deletes all the entries of the Alias Mapping Table with the 

    xentLogicalIndex as the secondary index

    Returns:

    - number of deleted entries for successful deletion

    - -1 for entry not found

    - -2 for stale logical entry

    NOTE: This API cannot be used to delete all indexes with

          xentLogicalIndex = 0. Use the deleteAliasMappingTableEntry API

          to delete such entries one by one, with the appropriate

          entPhysicalIndex specified.

extern int deleteAliasMappingPhysicalIndex(int xentPhysicalIndex);

  - Deletes all the entries in the Alias Mapping Table with the

    primary index same as the given physical index

    Returns:

    - number of deleted entries for on success

    - -1 for entry not found

    - -2 for stale physical entry

Physical Contains Table (entPhysicalContainsTable)

--------------------------------------------------

extern int addPhysicalContainsTableEntry(int entPhysicalIndex, int childIndex);

  - Adds an entry to the Physical Contains Table for the given entPhysicalIndex

    and childIndex. The entPhysicalContainedIn OID present in the Physical

    Table for the childIndex will be replaced by the entPhysicalIndex if the

    entPhysicalIndex has a lower index than the original one

    Returns:

    - 0 for successful addition

    - 1 if the entry already exists for the given entPhysicalIndex and

      childIndex.

    - -1 for failure to add.

extern int deletePhysicalContainsTableEntry(int parentIndex, int childIndex);

  - Deletes the parentIndex/childIndex entry present in the Physical Contains

    Table.

    Returns:

    - 0 for success

    - -1 for failure

    - -2 for stale entry (either parent or child, or both)

extern int deletePhysicalContainsParentIndex(int parentIndex);

  - Deletes all the entries in the Physical Contains Table where the parent

    index = parentIndex.

    Returns:

    - number of children deleted for that parent

    - -1 for failure

    - -2 for stale parent entry

extern int deletePhysicalContainsChildIndex(int childIndex);

  - Deletes all the entries in the Physical Contains Table where the child

    index = childIndex.

    Returns:

    - number of parents deleted for that child

    - -1 for failure

    - -2 for stale child entry

extern int* getPhysicalContainsChildren(int parentIndex);

  - Get the indexes for all the children in the Physical Contains

    Table, given a parent.

    Returns:

    - returns an array of indexes (integers) with null termination

    - NULL if no children, or not enough memory when allocating the array

    NOTE: The array is a copy and SHOULD be freed when done

Data Structures

---------------

The corresponding header files will be public interfaces as well, because the

data structures are defined there. 

typedef struct entPhysicalEntry_s {

    int entPhysicalIndex;

    char *entPhysicalDescr;

    oid *entPhysicalVendorType;

    int entPhysicalVendorTypeSize;

    int entPhysicalContainedIn;

    int entPhysicalClass;               /* see ENTPHYSICAL_CLASS_XXX */

    int entPhysicalParentRelPos;

    char *entPhysicalName;

    char *entPhysicalHardwareRev;

    char *entPhysicalFirmwareRev;

    char *entPhysicalSoftwareRev;

    char *entPhysicalSerialNum;

    char *entPhysicalMfgName;

    char *entPhysicalModelName;

    char *entPhysicalAlias;

    char *entPhysicalAssetID;

    int entPhysicalIsFRU;

    struct entPhysicalEntry_s *pNextEntry;

} entPhysicalEntry_t;

typedef struct entLogicalEntry_s {

    int   entLogicalIndex;

    char *entLogicalDescr;

    oid  *entLogicalType;

    int   entLogicalTypeSize;

    char *entLogicalCommunity;

    char *entLogicalTAddress;

    oid  *entLogicalTDomain;

    int   entLogicalTDomainSize;

    char *entLogicalContextEngineId;

    char *entLogicalContextName;

    struct entLogicalEntry_s* pNextEntry;

} entLogicalEntry_t;