================================================================================
This is Python implementation of OpenHPI baselib.
The implementation has been tested with CPython 2.5/2.6/2.7 and Iron Python 2.7.

================================================================================
Build and Install Instructions:

- For installation run "python setup.py install".

================================================================================
Usage Example:

See example.py as an example of using the Python OpenHPI baselib.

See example_lsres.py and example_ent.py as examples of using iteration
utility functions.

See example_handlers.py as an example of using the oHpiHandler*() API.

Default domain address is "localhost" or OPENHPI_DAEMON_HOST env. var. value.
Default domain address is 4743 or OPENHPI_DAEMON_PORT env. var. value.

================================================================================
Datatypes and API Representation:

All SAF HPI integer data types:
- SaHpiBoolT, SaHpiUint8(16,32,64)T, SaHpiInt8(16,32,64)T, enum types
are mapped to Python integer type.
One exception: arrays of SaHpiUint8T are mapped to Python string
(zero padded to full defined capacity).

Every SAF HPI struct or union is mapped to Python class.
The class name is the same as for the corresponding SAF HPI struct or union.
The class contais only public fields with the same names as 
the corresponding SAF HPI struct or union fields have. 

SAF HPI constants are defined in the HpiDataTypes submodule.
OpenHPI-specific constants are defined in the OhpiDataTypes submodule.

SAF HPI API are defined in the Hpi submodule. 
OpenHPI API are defined in the OHpi submodule. 

Every API returns result tuple.
The tuple consists of:
- error code
- output parts of SAHPI_INOUT parameters
- SAHPI_OUT and SAHPI_OUTNN parameters.
The error code is the first component of the tuple.
The rest parameters go in the same order they go in original SAF HPI API.

API parameters are mapped as the following:
- SAHPI_IN parameter is mapped to the ordinary Python function parameter.
- SAHPI_INOUT parameter is splitted:
-- The input part is mapped to the ordinary Python function parameter.
-- The output part is returned in result tuple.
- SAHPI_OUT and SAHPI_OUTNN parameters are returned in result tuple.

Example:

SaErrorT SAHPI_API saHpiGetIdByEntityPath (
    SAHPI_IN    SaHpiSessionIdT    SessionId,
    SAHPI_IN    SaHpiEntityPathT   EntityPath,
    SAHPI_IN    SaHpiRdrTypeT      InstrumentType,
    SAHPI_INOUT SaHpiUint32T       *InstanceId,
    SAHPI_OUT   SaHpiResourceIdT   *ResourceId,
    SAHPI_OUT   SaHpiInstrumentIdT *InstrumentId,
    SAHPI_OUT   SaHpiUint32T       *RptUpdateCount
);

is represented as

def saHpiGetIdByEntityPath(
    SessionId,
    EntityPath,
    InstrumentType,
    InstanceId
):

and the function returns
( ErrorCode, InstanceId, ResourceId, InstrumentId, RptUpdateCount ) tuple.

================================================================================
Utilities:

HpiUtil class provides the following utility functions:

- Set of functions for checking validity of an object of
a complex HPI data type X (representation of SAF HPI struct X):
-- public static bool checkX( x ) - (for example checkSaHpiTextBufferT)
--- The validation checks are:
---- x is not None
---- Any member of x that is of a complex data types is valid
---- If a member of x is a SaHpiUint8T[] array then the array length is valid.

- Set of functions for checking validity of an object of
a complex HPI data type X (representation of SAF HPI union X):
-- public static bool checkX( x, mod ) - (for example checkSaHpiSensorReadingUnionT)
---- x is not None
---- A member of x that matches modifier mod and is of a complex data types
is valid
---- If a member of x that matches modifier mod is a SaHpiUint8T[] array then
the array length is valid.

- For string <-> integer HPI Data Type X conversion:
-- def fromX( x ) - (for example FromSaHpiEventCategoryT)
-- def toX( str ) - (for example ToSaHpiEventCategoryT)

- For string <-> complex HPI Data Type conversion:
-- def fromSaHpiTextBufferT( tb )
-- def toSaHpiTextBufferT( str )
-- def fromSaHpiEntityPathT( ep )
-- def toSaHpiEntityPathT( str )

- For making unspecified, empty entity path and for entity path cloning:
- def makeUnspecifiedSaHpiEntityPathT()
- def makeRootSaHpiEntityPathT()
- def cloneSaHpiEntityPathT( ep )

================================================================================
Current Limitations:

- Only oHpiVersionGet(), oHpiDomainAdd() and oHpiHandler*() OpenHPI API are supported
- openhpiclient.conf is not supported

================================================================================
TODO List:

- Implemented openhpiclient.conf support
- Implement the rest of OpenHPI API
- Domain ID translation for SAF HPI API
- Entity root translation for SAF HPI API
- XTCA entity types in HpiUtils