portal - Domain Entity Access via the Domain Portal
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.
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.
classes (<domain name>_<class name>_CLASSID)
pre-defined instances (<domain name>_<class name>_<instance name>_INSTID)
attributes (<domain name>_<class name>_<attribute name>_ATTRID)
events (<domain name>_<class name>_<event name>_EVENT
states (<domain name>_<class name>_<state name>_STATE
the number of classes in the domain (<domain name>_CLASSCOUNT)
the number of instances of each class (<domain name>_<class name>_INSTCOUNT)
the number of attributes of each class (<domain name>_<class name>_ATTRCOUNT)
the number of events (classes with a state model) (<domain name>_<class name>_EVENTCOUNT)
the number of states (classes with a state model) (<domain name>_<class name>_STATECOUNT)
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.
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.
There is no class in the domain with the given class identifier.
There is no instance of the class with the given instance identifier.
There is no attribute of the class with the given attribute idenifier.
The instance identifier refers to an unused instance memory slot.
The given class has no state model.
There is no event for the class with the given event number.
There is no state for the class with the given state number.
Dynamic instance creation is not allowed for the given class.
The operation is not allowed for dependent attributes.
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.
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.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies an assigner in the domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
The number of bytes pointed to by eventParameters.
A non-negative integer value that identifies the event to signal.
A pointer to an object that contains the parameters for the event.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
A non-negative integer value that identifies an attribute of a class.
A pointer to a memory pointer where the reference to the attribute is placed.
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") ;
}
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
A non-negative integer value that identifies an attribute of a class.
A pointer to memory where the attribute value is placed.
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) ;
}
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
A non-negative integer value that identifies the event to signal.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
A non-negative integer value that identifies the event to signal.
A pointer to an object that contains the parameters for the event.
The number of bytes pointed to by eventParameters.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
A non-negative integer value that identifies the event to signal.
A pointer to memory from with the new attribute is retrieved.
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) ;
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an instance of a class.
A non-negative integer value that identifies an attribute of a class.
A pointer to memory from with the new attribute is retrieved.
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) ;
}
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.
A pointer to the portal data that describes a domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an attribute of a class.
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 ;
}
}
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
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.
A pointer to the portal data that describes a domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies an event in the class.
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 ;
}
}
A pointer to the portal data that describes a domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
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.
A pointer to the portal data that describes a domain.
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.
A pointer to the portal data that describes a domain.
A non-negative integer value that identifies a class in the domain.
A non-negative integer value that identifies a state in the class.
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.
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.
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.
Copyright © 2015 - 2020 by G. Andrew Mangogna