[ Table Of Contents | Keyword Index ]

portal(3) 1.0.1 micca "XUML Model Translation"

Name

portal - Domain Entity Access via the Domain Portal

Table Of Contents

Synopsis

Description

This manual page describes the micca portal functions. These functions allow operations on entities with a domain from outside of the domain code itself. The primary use case for the portal functions is for bridging between domains. Portal functions are also useful for testing or for building a test framework around a micca generated domain.

Micca Generated Data and Symbols

When micca generates the code for a domain, it also generates an initialized, externally scoped variable containing data that can be used in conjunction with the portal functions given here to query and operate on the domain. The portal data is placed in a variable whose name is given as, <domain name>__PORTAL, where <domain name> is the name given to the generated domain.

In addition to the portal data, micca generates a set of pre-processor macros that are included in the generated header file. These macros define a set of integer encodings for the various domain elements. For example, each class in the domain has a non-negative integer value symbolically defined by a pre-processor macro. This symbol may be used as a class identifier in the portal functions to specify on which class an operation is applied. Micca supplies symbolic encodings as follows for the domain entities. In parentheses, the naming convention for the generated macro names is given.

Additionally, for each event that carries supplimental event parameters, micca also places in the generated header file a structure definition for the parameters. The structure definition follows the naming convention: struct <domain name>_<class name>_<event name>__EPARAMS. Initialized values of these structures may be passed to portal functions to supply supplemental event data to signaled events.

Error Codes

Every portal function returns an integer value that indicates the success or failure of the operations. A non-negative return value indicates success. A negative return value indicates failure. The following pre-processor defined macros define the set of negative return values and their meaning.

MICCA_PORTAL_NO_CLASS

There is no class in the domain with the given class identifier.

MICCA_PORTAL_NO_INST

There is no instance of the class with the given instance identifier.

MICCA_PORTAL_NO_ATTR

There is no attribute of the class with the given attribute idenifier.

MICCA_PORTAL_UNALLOC

The instance identifier refers to an unused instance memory slot.

MICCA_PORTAL_NO_STATE_MODEL

The given class has no state model.

MICCA_PORTAL_NO_EVENT

There is no event for the class with the given event number.

MICCA_PORTAL_NO_STATE

There is no state for the class with the given state number.

MICCA_PORTAL_NO_DYNAMIC

Dynamic instance creation is not allowed for the given class.

MICCA_PORTAL_DEPENDENT_ATTR

The operation is not allowed for dependent attributes.

MICCA_PORTAL_SIZE_ERROR

The supplied value cannot be stored in the allocated storage space.

A function is supplied that returns a canonical string representation of an error code.

char const *const mrt_PortalErrorString(portalErrorCode)
int portalErrorCode (in)

An error value as returned from a portal function.

The mrt_PortalErrorString function translates a portal error code to a human readable string. By special dispensation, a value of zero for portalErrorCode is accepted and a string reference is returned for it. The value of NULL is returned for unknown error code values or if the run time was compiled with the pre-processor macro, MRT_NO_NAMES, defined.

Portal Functions

This section describes the set of function available through the portal to perform operations on a domain. These functions are intended primarily for use in creating bridge operations when multiple domains are used in an application. They are also useful for testing purposes.

int mrt_PortalAssignerCurrentState(portal, assignerId, instId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId assignerId (in)

A non-negative integer value that identifies an assigner in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of an assigner.

The mrt_PortalAssignerCurrentState obtains the current state number for the instId instance of the assignerId assigner in the domain described by portal. If successful, the return value of the function is the a small non-negative number that is the encoded value of the current state. This value will match one of the pre-processor macro values defined in the generated header file of the domain. Upon failure, the return value is one of the portal error codes.

int mrt_PortalCancelDelayedEvent(portal, classId, instId, eventNumber)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_EventCode eventNumber (in)

A non-negative integer value that identifies the event to cancel.

The mrt_PortalCancelDelayedEvent function cancels the eventNumber event to the instId instance of class, classId, in the domain described by portal. N.B. it is not an error to cancel an event that was never signaled or to cancel an event that was signaled but has already been dispatched. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int mrt_PortalCreateInstance(portal, classId, initialState)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_StateCode initialState (in)

A small non-negative interger that gives the initial state into which the new created instance is placed.

The mrt_PortalCreateInstance function creates an instance of classId in the domain described by portal. The instance is placed in the initialState state. If the class given by classId does not have a state model, then initialState must be given by MRT_StateCode_IG. If the class given by classId does have a state model and if initialState is given as MRT_StateCode_IG, then the new created instance is placed in the default initial state. The initialState may not be given as the pseudo-initial state for those classes that have creation events. In all cases, no state activity is executed by the new created instance. If successful, the return value of the function is the a small non-negative number that is the instance identifier for the newly created instance. Upon failure, the return value is one of the portal error codes.

N.B. the instance created by this function is not properly initialized since no attribute values have been set. It is encumbent upon the caller of this function to use the mrt_PortalUpdateAttr function to set a value for all the attributes of the newly created instance. Also note that it is not possible to create an association between class instances via the portal functions. For this reason, instance creation where the class instances participate in unconditional relationships must usually be done by constructing a domain operation in the domain containing the class. Also for this reason, instance creation via portal functions is often best accomplished asynchronously using creation events so that a state action is run to place the newly created instance into a consistent state and create any relationship linkages.

int mrt_PortalCreateInstanceAsync(portal, classId, eventNumber, eventParameters, paramSize)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

size_t paramSize (in)

The number of bytes pointed to by eventParameters.

MRT_EventCode eventNumber (in)

A non-negative integer value that identifies the event to signal.

void const * eventParameters (in)

A pointer to an object that contains the parameters for the event.

size_t paramSize (in)

The number of bytes pointed to by eventParameters.

The mrt_PortalCreateInstanceAsync function creates an instance of classId in the domain described by portal by signaling the creation event given by eventNumber. If the event requires any supplemental event parameters, they are given in the memory pointed to by eventParameters which is paramSize number of bytes. The new created instance is placed in its pseudo-initial state and eventNumber is signaled to it. When the event is dispatched, the state action associated with transition is executed. If successful, the return value of the function is the a small non-negative number that is the instance identifier for the newly created instance. Upon failure, the return value is one of the portal error codes.

N.B. the instance created by this function is not properly initialized since no attribute values have been set. It is encumbent upon the caller of this function to use the mrt_PortalUpdateAttr function to set a value for all the attributes of the newly created instance.

int mrt_PortalDeleteInstance(portal, classId, instId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

The mrt_PortalDeleteInstance deletes the instId instance of the classId class in the domain described by portal.

int mrt_PortalGetAttrRef(portal, classId, instId, attrId, pref, size)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_AttrId attrId (in)

A non-negative integer value that identifies an attribute of a class.

void ** pref (out)

A pointer to a memory pointer where the reference to the attribute is placed.

MRT_AttrSize * size (out)

A pointer to an object where the number of bytes occupied by the attribute is placed.

The mrt_PortalGetAttrRef function obtains a pointer reference to an attribute value. The preferred way to access attributes is to use the mrt_PortalReadAttr or mrt_PortalUpdateAttr functions. However, for attributes values that are arrays, it is most convenient to deal with them by references rather than by value. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

char const *cycletype ;
MRT_AttrSize typelen ;
int pcode = mrt_PortalGetAttrRef(&wmctrl__PORTAL,
        WMCTRL_WASHINGCYCLE_CLASSID,
        WMCTRL_WASHINGCYCLE_NORMAL_INSTID,
        WMCTRL_WASHINGCYCLE_WASHINGCYCLE_ATTRID,
        (void **)&cycletype, &typelen) ;
assert(pcode == 0) ;
if (strcmp(cycletype, "Normal") == 0) {
    printf("found the normal washing cycle\n") ;
}
int mrt_PortalInstanceCurrentState(portal, classId, instId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

The mrt_PortalInstanceCurrentState obtains the current state number for the instId instance of the classId class in the domain described by portal. If successful, the return value of the function is the a small non-negative number that is the encoded value of the current state. This value will match one of the pre-processor macro values defined in the generated header file of the domain. Upon failure, the return value is one of the portal error codes.

int mrt_PortalReadAttr(portal, classId, instId, attrId, dst, dstSize)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_AttrId attrId (in)

A non-negative integer value that identifies an attribute of a class.

void * dst (out)

A pointer to memory where the attribute value is placed.

MRT_AttrSize dstSize (in)

The number of bytes pointed to by dst.

The mrt_PortalReadAtt function reads the value of an attribute of a class instance. The value is read from the domain described by portal, the class given by classId, the instance given by instId and the attribute given by attrId. The attribute value is copied to the memory pointed to by dst. The number of bytes pointed to by dst is given by dstSize and no more than dstSize bytes are copied to dst. If successful, the return value of the function is the number of bytes actually copied to dst. Upon failure, the return value is one of the portal error codes.

unsigned washduration ;
int pcode = mrt_PortalReadAttr(&wmctrl__PORTAL,
        WMCTRL_WASHINGCYCLE_CLASSID,
        WMCTRL_WASHINGCYCLE_NORMAL_INSTID,
        WMCTRL_WASHINGCYCLE_WASHDURATION_ATTRID,
        &washduration, sizeof(washduration)) ;
if (pcode == sizeof(washduration)) {
    printf("normal washing duration is %u\n", washduration) ;
}
int mrt_PortalRemainingDelayTime(portal, classId, instId, eventNumber, delayRef)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_EventCode eventNumber (in)

A non-negative integer value that identifies the event to signal.

MRT_DelayTime * delayRef (out)

A pointer to an object of type MRT_DelayTime where the remaining delay is placed.

The mrt_PortalRemainingDelayTime function returns by reference via delayRef the minimum number of milliseconds before the eventNumber is dispatched to the classId instance in the domain described by portal. If there is no event given by eventNumber for the classId instance or if the event has already been dispatched, then the returned remaining time is set to zero. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int mrt_PortalSignalDelayedEvent(portal, classId, instId, eventNumber, eventParameters, paramSize, delay)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_EventCode eventNumber (in)

A non-negative integer value that identifies the event to signal.

void const * eventParameters (in)

A pointer to an object that contains the parameters for the event.

size_t paramSize (in)

The number of bytes pointed to by eventParameters.

MRT_DelayTime delay (in)

The minimum number of milliseconds that is to elapse before the event is dispatched.

The mrt_PortalSignalDelayedEvent function signals the eventNumber event to the instId instance of class, classId, in the domain described by portal delayed in time by at least delay milliseconds. It the event carries supplimental parameters, they are supplied by reference via eventParameters which points to paramSize number of bytes. If the event requires no parameters, then eventParameters and paramSize are given as NULL and 0, respectively. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int mrt_PortalSignalEvent(portal, classId, instId, eventNumber, eventParameters, paramSize)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_EventCode eventNumber (in)

A non-negative integer value that identifies the event to signal.

void const * eventParameters (in)

A pointer to memory from with the new attribute is retrieved.

size_t paramSize (in)

The number of bytes pointed to by eventParameters.

The mrt_PortalSignalEvent function signals the eventNumber event to the instId instance of class, classId, in the domain described by portal. It the event carries supplimental parameters, they are supplied by reference via eventParameters which points to paramSize number of bytes. If the event requires no parameters, then eventParameters and paramSize are given as NULL and 0, respectively. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

struct wmctrl_ClothesTub_Fill__EPARAMS = {
    .temp = WT_Hot
} ;
int pcode = mrt_PortalSignalEvent(&wmctrl__PORTAL,
        WMCTRL_CLOTHESTUB_CLASSID,
        WMCTRL_CLOTHESTUB_CT1_INSTID,
        WMCTRL_CLOTHESTUB_FILL_EVENT,
        &wmctrl_ClothesTub_Fill__EPARAMS,
        sizeof(wmctrl_ClothesTub_Fill__EPARAMS)) ;
assert(pcode == 0) ;
int mrt_PortalUpdateAttr(portal, classId, instId, attrId, src, srcSize)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_InstId instId (in)

A non-negative integer value that identifies an instance of a class.

MRT_AttrId attrId (in)

A non-negative integer value that identifies an attribute of a class.

void const * src (in)

A pointer to memory from with the new attribute is retrieved.

MRT_AttrSize srcSize (in)

The number of bytes pointed to by src.

The mrt_PortalUpdateAttr modifies the value of the attrId attribute of the instId instance in the classId class of the domain described by portal. The new attribute value is obtain by reference from src which points to srcSize bytes of memory. If successful, the return value of the function is the number of bytes actually copied from src. Upon failure, the return value is one of the portal error codes.

unsigned washduration = 100 ;
int pcode = mrt_PortalUpdateAttr(&wmctrl__PORTAL,
        WMCTRL_WASHINGCYCLE_CLASSID,
        WMCTRL_WASHINGCYCLE_NORMAL_INSTID,
        WMCTRL_WASHINGCYCLE_WASHDURATION_ATTRID,
        &washduration, sizeof(washduration)) ;
if (pcode == sizeof(washduration)) {
    printf("normal washing duration is now %u\n", washduration) ;
}

Introspection Functions

The functions in this section return information about the domain and the elements in the domain. These functions allow programs to inquire about the domain meta-data during run time.

int mrt_PortalClassAttributeCount(portal, classId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

The mrt_PortalClassAttributeCount function returns the number of attributes contained in the classId class in the domain described by portal. If successful, the return value of the function is a non-negative count of the number of attributes of classId. Upon failure, the return value is one of the portal error codes.

int mrt_PortalClassAttributeName(portal, classId, attrId, nameRef)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_AttrId attrId (in)

A non-negative integer value that identifies an attribute of a class.

char const ** const nameRef (out)

A pointer to a character pointer by which the attribute name is returned.

The mrt_PortalClassAttributeName function obtains the name of the attrId attribute of the classId class in the domain described by portal. The name is returned via nameRef as a pointer to a NUL terminated string. If the domain was compiled with the preprocessor symbol MRT_NO_NAMES defined, then the value placed in the location pointed to by nameRef is NULL. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int attrCount = mrt_PortalClassAttributeCount(&wmctrl__PORTAL,
        WMCTRL_WASHINGCYCLE_CLASSID) ;
assert(attrCount >= 0) ;
for (int attrId = 0 ; attrId < attrCount ; attrId++) {
    char const *attrName ;
    int pcode = mrt_PortalClassAttributeName(&wmctrl__PORTAL,
            WMCTRL_WASHINGCYCLE_CLASSID, attrId, &attrName) ;
    if (pcode == 0) {
        if (attrName != NULL) {
            printf("attribute %d is named %s\n", attrId, attrName) ;
        } else {
            printf("no name available for attribute %d\n", attrId) ;
        }
    } else {
        fprintf(stderr, "failed to get attribute name, %s\n",
                mrt_PortalErrorString(pcode)) ;
        break ;
    }
}
int mrt_PortalClassAttributeSize(portal, classId, attrId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_AttrId attrId (in)

A non-negative integer value that identifies an attribute of a class.

The mrt_PortalClassAttributeSize function returns the number of bytes occupied by a value of the attrId of the classId class in the domain described by portal. If successful, the return value of the function is a positive number of bytes occupied by the attribute value. Upon failure, the return value is one of the portal error codes.

int mrt_PortalClassEventCount(portal, classId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

The mrt_PortalClassEventCount function returns the number of events associated with the state model of the classId class in the domain described by portal. If successful, the return value of the function is a positive number giving the number of events in the state model. Events are numbered from 0 to the return value of the function minus one. Upon failure, the return value is one of the portal error codes.

int mrt_PortalClassEventName(portal, classId, eventNumber nameRef)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_EventCode eventNumber (in)

A non-negative integer value that identifies an event in the class.

char const ** const nameRef (out)

A pointer to a character pointer by which the event name is returned.

The mrt_PortalClassEventName function obtains the name of the eventNumber event of the classId class in the domain described by portal. The name is returned via nameRef as a pointer to a NUL terminated string. If the domain was compiled with the preprocessor symbol MRT_NO_NAMES defined, then the value placed in the location pointed to by nameRef is NULL. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int eventCount = mrt_PortalClassEventCount(&wmctrl__PORTAL,
        WMCTRL_WASHINGMACHINE_CLASSID) ;
assert(eventCount > 0) ;
for (int eventId = 0 ; eventId < eventCount ; eventId++) {
    char const *eventName ;
    int pcode = mrt_PortalClassEventName(&wmctrl__PORTAL,
            WMCTRL_WASHINGMACHINE_CLASSID, eventId, &eventName) ;
    if (pcode == 0) {
        if (eventName != NULL) {
            printf("event %d is named %s\n", eventId, eventName) ;
        } else {
            printf("no name available for event %d\n", eventId) ;
        }
    } else {
        fprintf(stderr, "failed to get event name, %s\n",
                mrt_PortalErrorString(pcode)) ;
        break ;
    }
}
int mrt_PortalClassInstanceCount(portal, classId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

The mrt_PortalClassInstanceCount function returns the maximum number of instances that may exist for the classId class in the domain described by portal. If successful, the return value of the function is a positive number giving the count of the instance storage slots of classId. Instances are identified via sequential integers from zero to the return value of the function minus one. Upon failure, the return value is one of the portal error codes.

int mrt_PortalClassName(portal, classId, nameRef)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

char const ** const nameRef (out)

A pointer to a character pointer by which the class name is returned.

The mrt_PortalClassName function obtains the name of the classId class in the domain described by portal. The class name is returned via nameRef as a pointer to a NUL terminated string. If the domain was compiled with the preprocessor symbol MRT_NO_NAMES defined, then the value placed in the location pointed to by nameRef is NULL. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int mrt_PortalClassStateCount(portal, classId)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

The mrt_PortalClassStateCount function returns the number of states associated with the state model of the classId class in the domain described by portal. If successful, the return value of the function is a positive number giving the number of events in the state model. Events are numbered from 0 to the return value of the function minus one. Upon failure, the return value is one of the portal error codes.

int mrt_PortalClassStateName(portal, classId, stateCode nameRef)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

MRT_ClassId classId (in)

A non-negative integer value that identifies a class in the domain.

MRT_StateCode stateCode (in)

A non-negative integer value that identifies a state in the class.

char const ** const nameRef (out)

A pointer to a character pointer by which the state name is returned.

The mrt_PortalClassStateName function obtains the name of the stateCode state of the classId class in the domain described by portal. The name is returned via nameRef as a pointer to a NUL terminated string. If the domain was compiled with the preprocessor symbol MRT_NO_NAMES defined, then the value placed in the location pointed to by nameRef is NULL. If successful, the return value of the function is zero. Upon failure, the return value is one of the portal error codes.

int mrt_PortalDomainClassCount(portal)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

The mrt_PortalDomainClassCount function returns the number of classes defined in the domain described by portal. Classes are identified by numbers from 0 to the return value of the function minus one.

char const *mrt_PortalDomainName(portal)
MRT_DomainPortal const *const portal (in)

A pointer to the portal data that describes a domain.

The mrt_PortalDomainName function returns a pointer to a NUL terminated string giving the name of the domain described by portal. If the domain was compiled with the preprocessor symbol MRT_NO_NAMES defined, then the return value is NULL.

See Also

embedded, micca

Keywords

translation