V4 Design: epicsTypes

EPICS: epicsTypes - C++ definitions

May 19 2005

Overview

This document describes the C++ class definitions for storing data that is accessable from outside the code that manages the date. A primary example is fields in ioc records that can be accessed from outside record support.

epicsTypes

epicsTypes.h contains the following:

    /* The following may require OSD definitions*/
    typedef bool               epicsBoolean;
    typedef char               epicsOctet;
    typedef short              epicsInt16;
    typedef unsigned short     epicsUInt16;
    typedef int                epicsInt32;
    typedef unsigned int       epicsUInt32;
    typedef long long          epicsInt64;
    typedef unsigned long long epicsUInt64;
    typedef float              epicsFloat32;
    typedef double             epicsFloat64;
   
    enum epicsType {
        epicsUnknownT,
        epicsBooleanT,     // epicsBoolean
        epicsOctetT,       // epicsOctet
        epicsInt16T,       // epicsInt16
        epicsUInt16T,      // epicsUInt16
        epicsInt32T,       // epicsInt32
        epicsUInt32T,      // epicsUInt32
        epicsInt64T,       // epicsInt64
        epicsUInt64T,      // epicsUInt64
        epicsFloat32T,     // epicsFloat32
        epicsFloat64T,     // epicsFloat64
        epicsStringT,      // described in epicsString.h
        epicsArrayT,       // described in epicsArray.h
        epicsStructT       // described in epicsStruct.h
    };

Discussion of epicsTypes

epicsTypes provides classes for describing data that can be introspected and can be passed between different platforms. All data that is sent to or received from EPICS records will be composed of epicsTypes.

The types epicsBooleanT, ..., epicsFloat64T all map to a C++ standard type. It may be necessary to provide operating system dependent definitions for some of the types. For example on some architectures a epicsInt64 may have to be defined as a long rather than a long long.

The types epicsStringT, epicsArrayT , and epicsStructT are designed so that any data can be described, introspected, and passed over a network. An epicsStruct can contain epicsArrays and epicsStructs and a epicsArray can be an array of any epicsType except epicsUnknownT.

epicsUnknownT is provided in case something expected to produce an epicsType fails.

epicsString

epicsString.h contains the following:

    class EpicsUTF_8Buffer;
    class EpicsStringTranslate;
    
    /*EpicsString holds UTF-8 characters*/
    class EpicsString  {
    public:
        EpicsUTF_8Buffer    *pbuffer;
        EpicsStringTranslate *ptranslate;
    };

    enum epicsStringBufferType {
        epicsStringBufferContiguous,
        epicsStringBufferSegmented,
    };

    class EpicsUTF_8Buffer {
    public:
        virtual bool allocate(epicsInt32 capacity) = 0;
        virtual void release(DbfString *pstring, bool onlyStorage) = 0;
        virtual epicsInt32 capacity() = 0;
        virtual epicsInt32 limit() = 0;
        virtual void limit(epicsInt32 newLimit) = 0;
        virtual epicsInt32 position() = 0;
        virtual void position(epicsInt32 newPosition) = 0;
        virtual void clear() = 0;
        virtual void flip() = 0;
        virtual epicsInt32 remaining() = 0;
        virtual epicsOctet get() = 0;
        virtual void put(epicsOctet value) = 0;
        virtual epicsBoolean isEqual(EpicsUTF_8Buffer *pbuffer) = 0;
        virtual epicsBoolean isEqual(
                     const epicsOctet *pstring, epicsInt32 len) = 0;
        virtual epicsUint16 hash() = 0;
    };

    class EpicsStringTranslate {
        virtual bool isCharString(EpicsUTF_8Buffer *pbuffer) = 0;
        virtual epicsInt32 length(EpicsUTF_8Buffer *pbuffer) = 0;
        virtual epicsInt32 length(char *p,epicsInt32 len) = 0;
        virtual epicsInt32 length(wchar_t *p,epicsInt32 len) = 0;
        virtual epicsInt32 toChar(EpicsUTF_8Buffer *buffer,
                            char *pcharstring, epicsInt32 maxsize) = 0;
        virtual epicsInt32 toChar(EpicsUTF_8Buffer *buffer,
                            wchar_t *pcharstring, epicsInt32 maxsize) = 0;
        virtual void fromChar(EpicsUTF_8Buffer *pbuffer,
                              const char *pcharstring, epicsInt32 size) = 0;
        virtual void fromChar(EpicsUTF_8Buffer *buffer,
                              const wchar_t *pcharstring,epicsInt32 size) = 0;
    };

    typedef EpicsUTF_8Buffer *(EpicsUTF_8BufferAllocate)();
    class EpicsUTF_8BufferFactory {
    public:
        static EpicsUTF_8Buffer * allocate(const epicsStringBufferType type);
        static void register(const epicsStringBufferType type,
                         EpicsUTF_8BufferAllocate allocater,
                         const epicsStringBuffer *pbuffer);
    };

    typedef EpicsStringTranslate  *(EpicsStringTranslateAllocate)();
    class EpicsStringTranslateFactory {
    public:
        static epicsTranslateBuffer * find(const char * factoryType);
        static void register(const char * factoryType,
                         EpicsStringTranslateAllocate allocater,
                         const EpicsStringTranslate *ptranslate);
    };
    /* at least the following factory types are supported
     * ASCII - 7 bit ascii
     * DEFAULT - The default locale
     *           NOTE: As distributed base supports Unicode Basic Latin
     */

Discussion of epicsString

An EpicsString contains UTF-8 encoded character strings. It has the following fields:

pbuffer

The address of a EpicsUTF_8Buffer, which is a class that manages the string storage.

ptranslate

The address of a EpicsStringTranslate, which is an interface that converts between a UTF-8 encoded string and a char or <wchar_t> encoded string.

Both EpicsUTF_8Buffer and EpicsStringTranslate are pure abstract base classes because multiple implementation of each are allowed.

EpicsUTF_8Buffer

NOTE: EpicsUTF_8Buffer uses ideas from the Java nio Buffer class.

An EpicsUTF_8Buffer contains storage for a UTF-8 encoded string. In addition to holding storage for a string, a string buffer keeps the following information.

capacity

The number of octets allocated, i.e. the number of UTF-8 characters the buffer can hold.

limit

The current size, i.e. the index of the first octet that can not hold data. Data can not be read from or written into a buffer beyond limit. When data is being written to a buffer limit is normally equal to capacity. When data is being read from a buffer limit is normally less than capacity and indicates the end of valid data.

position

The index of the first octet in the buffer at which data is being read or written.

EpicsUTF_8Buffer has the following methods:

allocate

This allocates space for capacity bytes. If capacity is not zero when this is called the old storage is freed or reused and the octets spanned by position, limit appear in the newly allocated storage.

release

Frees storage. If onlyStorage is true then the storage for the string is freed and capacity is set to zero; otherwise the string storage and the storage for EpicsUTF_8Buffer itself is freed.

capacity

return the capacity

limit

Two methods are available, one to get the current limit and one to set the limit.

position

Two methods are available, one to get the current position and one to set the position.

clear

Sets limit = capacity and position = 0. This prepares a buffer for writing.

flip

Sets limit = position and position = 0. After writing to a buffer this method prepares the buffer for reading.

remaining

returns (limit - position)

get

returns the octet at position and increments position. An exception is thrown if position = limit.

put

writes an octet at position and increments position. An exception is thrown if position = limit.

isEqual(EpicsUTF_8Buffer *)

Compares the string stored in the buffer with a string stored in a different buffer. This is normally called by code that uses an EpicsUTF_8Buffer.

isEqual(epicsOctet *pstring, epicsInt32 len)

Compares the string stored in the buffer with a string supplied by the caller. This is normally called by EpicsUTF_8Buffer itself to compare it's string with the string stored in another buffer.

hash

implement a hash on the octets stored in the buffer.

EpicsStringTranslate

EpicsStringTranslate implements code that converts between strings stored in an EpicsUTF_8Buffer and char * or wchar_t * null terminated strings. Multiple implementations are provided.

EPICS base supplies implementations that support 7 bit ascii and basic latin. Implementations that support other character encodings may also be provided.

EpicsStringTranslate has the following methods:

isCharString

Determines if the string stored in the EpicsUTF_8Buffer be converted to a char * array.

length

Return the number of characters in the string. Three methods are provided. The first finds the number of characters stored in an EpicsUTF_8Buffer . The other two return the number of octets required to store the string in UTF-8 encoding. One accepts a char * array and the other a wchar * array.

toChar

Two methods are provided. One to convert the string stored in EpicsUTF_8Buffer, the substring defined by position,limit, to a char * array and the other to a wchar_t * array.

fromChar

Two methods are provided. One to convert a char * array to a EpicsUTF_8Buffer array. The other converts a wchar * array.

EpicsUTF_8BufferFactory

This is a class for allocating an EpicsUTF_8Buffer and also for registering EpicsUTF_8Buffer implementations.

EpicsStringTranslateFactory

This is a class for allocating an EpicsStringTranslate and also for registering EpicsStringTranslate implementations.

epicsArray

epicsArray.h contains the following:

    class EpicsArray {
    public:
        epicsUInt32  capacity;  //capacity in number of elements 
        epicsType   type; 
        void      *pstorage; // storage for capacity elements of type
    };

    class EpicsArrayBounds {
        epicsUInt32 low;
        epicsUInt32 high;
    };
    class EpicsNdimArray {
    public:
        epicsUInt32  capacity;  //capacity in number of elements 
        epicsInt16  ndim;      // number of dimensions
        epicsType   type; 
        void      *pstorage; // storage for capacity elements of type
        EpicsArrayBounds bounds[]; // bounds[ndim]
    };
        

Discussion of epicsArray

epicsStruct

epicsStruct.h contains the following:

    class EpicsStructField {
    public:
        EpicsString name;
        epicsType   type;
    };
   
    class EpicsStructDef{
    public:
        DbfString    name;
        Interface    *plifetime; // references a StructDbdLifetime
        epicsInt16     nfields;
        EpicsStructField *pfield[]; // ptr to array of ptr to EpicsStructField
    };

    class EpicsStruct{
    public:
        EpicsStructDef *pstructDef;
        void    *pstorage;
    };