|
1.
|
The cdevCallback Class
|
|
Overview of the
cdevCallback
Class
|
The cdevCallback C++ class is used by the sendCallback method to specify the
callback function that should be executed when the message has been processed.
This class also allows the caller to include a user specified argument that will be
provided as a parameter in the callback function when it is executed.
Figure 1:
Object model of the cdevCallback class
|
|
class cdevCallback
methods:
callbackFunction (void) : cdevCallbackFunction
userarg (void) : void *
operator == (cdevCallback &) : int
operator != (cdevCallback &) : int
fireCallback (...) : void
isTransactionDone(void) {static}: int
|
|
|
|
Public Methods of
the cdevCallback
Class
|
|
cdevCallback
|
cdevCallback (void);
cdevCallback (cdevCallbackFunction func, void * userarg);
cdevCallback (cdevCallback & callback);
This is the constructor for the callback object. It sets the internal
pointers to the user specified callback function and userarg
pointer.
|
|
callbackFunction
|
cdevCallbackFunction callbackFunction (void);
Obtains a pointer to the callback function that is stored within
the cdevCallback object.
|
|
userarg
|
void * userarg (void);
Obtains a pointer to the user argument that is stored within the
cdevCallback object.
|
|
operator ==
|
int operator == (const cdevCallback& callback);
Used to compare two cdevCallback objects. Two objects are
considered equal if they point to the same callback function and
user argument.
|
|
operator !=
|
int operator != (const cdevCallback& callback);
Used to compare two cdevCallback objects. Two objects are
considered equal if they point to the same callback function and
user argument.
|
|
fireCallback
|
void fireCallback ( int status,
void * userarg,
cdevRequestObject & req,
cdevData & result,
int partialTransaction = 0);
This method allows the caller to dispatch the callback function
with the specified parameters. If the callback represents a
response that is one of many that will occur, then the
partialTransaction flag should be set to non-zero. The value of
this flag can be retrieved by calling the static
cdevCallback::isTransactionDone method.
|
|
isTransactionDone
|
int isTransactionDone ( void );
This method returns an integer indicating if this callback
indicates the end of the transaction. In the event of multi-part
transactions such as "monitorOn", this method will return a
non-zero value indicating that more callbacks can be expected.
In the event of monotonic operations such as "get" or "set", or
when the last monitor callback is received, this method will
return zero.
|
|
|
2.
|
The cdevCollection Class
|
|
Overview of the
cdevCollection
Class
|
The cdevCollection class provides a mechanism for sending a message to a collection
of named devices. The class maintains a list of CDEV devices that are associated
through an entry in the CDEV DDL file. The developer also dynamically create a
cdevCollection device.
Figure 2:
Object Model of the cdevCollection Class
|
|
cdevCollection
methods:
cdevCollection (char *, cdevSystem &)
~cdevCollection (void) :{virtual}
getRequestObject (char *, cdevRequestObject *&) :{virtual} int
attachRef (char *) :{static} cdevCollection &
attachPtr (char *) :{static} cdevCollection *
attachRef (char *, cdevSystem &) :{static} cdevCollection *
attachPtr (char *, cdevSystem &) :{static} cdevCollection &
detach (cdevCollection &) :{static} void
detach (cdevCollection *) :{static} void
className (void) :{virtual} char *
add (char *) : int
add (int, char *, ...) : int
add (int, char **) : int
add (char **) : int
addRegexp (char *) : int
remove (char *) : int
remove (int, char *, ...) : int
remove (int, char **) : int
remove (char **) : int
removeRegexp (char *) : int
|
|
|
|
Public Methods of
the
cdevCollection
Class
|
|
cdevCollection
|
cdevCollection (char * name, cdevSystem & system);
This is the constructor for the cdevCollection class. It has the
following properties.
|
This method is protected to prevent cdevCollections from
being instantiated directly. New cdevCollection instances
are created by using the attachPtr or attachRef method of
the cdevCollection class.
The name that is provided to the cdevCollection is the
device name that CDEV will use to refer to it. The name
must be unique within the CDEV system of objects and
cannot be the same as the name of any regular cdevDevice
that exists in the CDEV DDL file.
The cdevSystem reference that is provided is the
cdevSystem instance that will be used to poll, pend and
flush the cdevCollection object.
If the name provided is the name of a cdevCollection that
has been specified in the CDEV DDL file, then the list of
devices will be populated from the names that are
specified. Otherwise, an empty cdevCollection instance will
be created.
|
~cdevCollection
|
virtual ~cdevCollection (void);
This is the destructor for a cdevCollection object. It has the
following properties.
|
This method is protected to prevent the cdevCollection
object from being destroyed by the application. This
method should only be called by the cdevSystem object
when the application is terminating.
Because the cdevCollection object will normally be referred
to as a cdevDevice object, this destructor is virtual to
ensure that the 'most senior' destructor is called first.
This method will delete all device name strings that are
associated with the cdevCollection object.
|
getRequestObject
|
virtual int getRequestObject ( char *msg,
cdevRequestObject* &req);
This method is called in order to obtain the cdevRequestObject
associated with the specified device/msg combination. This
method returns CDEV_SUCCESS if the cdevRequestObject
was successfully obtained. This method has the following
properties.
|
The cdevRequestObject pointer that is returned is actually
a pointer to a cdevCollectionRequest object.
If a cdevCollectionRequest already exists for the specified
device/msg combination, it will be returned. Otherwise, the
method will call the attachPtr method of the
cdevCollectionRequest in order to obtain a new request
object.
|
attachRef/attachPtr
|
cdevCollection & attachRef (char * name);
cdevCollection & attachRef (char * name, cdevSystem & sys);
cdevCollection * attachPtr (char * name);
cdevCollection * attachPtr (char * name, cdevSystem &sys);
These methods are used to obtain a pointer or reference to a
cdevCollection object. The name variable specifies the name of
the collection to be attached. These method have the following
properties.
|
All functionality for these methods is stored in the attachPtr
(char *, cdevSystem &) method. All other methods will call
this one.
The method will first determine if the device has already
been created. If it has been created and its className
method returns "cdevCollection", then the existing
cdevCollection will be returned. If a non-collection
cdevDevice of the same name has already been
constructed, then NULL will be returned.
If a device with the specified name has not already been
created, then the method will search the cdevDirectory for
the specified name. If the device name is in the
cdevDirectory AND is of class "collection", then a new
cdevCollection will be instantiated and returned. If a non-
collection cdevDevice of the same name exists in the
cdevDirectory, then NULL will be returned.
If a device with the specified name has not been
instantiated and does not exist in the cdevDirectory, then a
new, empty cdevCollection will be created with the
specified name.
If NULL is returned to one of the attachRef methods, then a
reference to a cdevErrorCollection object will be returned to
the caller.
The refCount property of the cdevCollection will be
incremented each time a copy of the cdevCollection object
is obtained by the application.
|
detach
|
int detach (cdevCollection & col);
int detach (cdevCollection * col);
This method is called to detach a pointer or reference to a
cdevCollection object. It has the following properties.
|
This method decrements the refCount property of the
cdevCollection object.
When the refCount property is decremented to 0, then the
cdevCollection object will be deleted.
|
className
|
char * className (void);
This method returns the name of the class; "cdevCollection". If
the developer inherits a service specific cdevCollection, then
this method should not be altered or overridden.
|
|
add
|
int add (char *name);
This method will add the individual name to the list of device
names that are in the cdevCollection. This method has the
following properties.
|
If a cdevCollectionRequest object has been instantiated for
this cdevCollection device, then the operation will fail and
CDEV_INVALIDOP will be returned.
If the name provided is NULL or empty, then the operation
will fail and CDEV_INVALIDOP will be returned.
If the name specified already exists in the collection of
names, then the operation will fail and CDEV_WARNING
will be returned.
If the name specified is not already in the list, then the
method will append the device name to the end of the list
and return CDEV_SUCCESS.
|
add
|
int add (int num, char *firstname,...);
This method will attempt to add a list of num names to the
cdevCollection. This method has the following properties.
|
If a cdevCollectionRequest object has been instantiated for
this cdevCollection device, then the operation will fail and
CDEV_INVALIDOP will be returned.
This method will call the add (char *name) method for each
name that is specified.
If the add method fails to add any of the device name
strings to the list, then the error code that was generated by
the call to add (char * name) will be returned.
If an error occurs while adding a name to the list, the
method will continue with the next name until the last name
is reached.
If no errors occur while adding names to the list, then
CDEV_SUCCESS will be returned to the caller.
|
add
|
int add (int num, char **names);
This method will attempt to add num device names from the
names array to the list using the add (char *name) method of
the cdevCollection. This method has the same properties as
the add (int num, char * firstname,...) method.
|
|
add
|
int add (char **names);
This method will attempt to add each device name from the
NULL terminated names array to the list using the add (char
*name) method of the cdevCollection. This method has the
same properties as the add (int num, char * firstname,...)
method.
|
|
addRegexp
|
int addRegexp (char *regexp);
This method will query the system name server for the list of all
names in the cdevDirectory that match the specified regular
expression. the array of names will be added to the list using
the add (int num, char ** names) method and the result of this
operation will be returned.
|
|
remove
|
int remove (char *name);
This method will remove the specified device name from list of
device names that is stored in the cdevCollection object. This
method has the following properties.
|
If a cdevCollectionRequest object has been instantiated for
this cdevCollection device, then the operation will fail and
CDEV_INVALIDOP will be returned.
If the name provided is NULL or empty, then the operation
will fail and CDEV_WARNING will be returned.
If the name specified does not exist in the collection of
names, then the operation will fail and CDEV_WARNING
will be returned.
If the name specified exists in the list, then it will be
removed and CDEV_SUCCESS will be returned.
|
remove
|
int remove (int num, char *name,...);
This method will attempt to remove a list of num names from
the cdevCollection. This method has the following properties.
|
If a cdevCollectionRequest object has been instantiated for
this cdevCollection device, then the operation will fail and
CDEV_INVALIDOP will be returned.
This method will call the remove (char *name) method for
each name that is specified.
If the remove method fails to remove any of the device
name strings from the list, then the error code that was
generated by the call to remove (char * name) will be
returned.
If an error occurs while removing a name from the list, the
method will continue with the next name until the last name
is reached.
If no errors occur while removing names from the list, then
CDEV_SUCCESS will be returned to the caller.
|
remove
|
int remove (int num, char **names);
This method will attempt to remove num device names as
specified in the names array from the list using the remove
(char *name) method of the cdevCollection. This method has
the same properties as the remove (int num, char * name,...)
method.
|
|
remove
|
int remove (char **names);
This method will attempt to remove each device name as
specified in the NULL terminated names array from the list
using the remove (char *name) method of the cdevCollection.
This method has the same properties as the remove (int num,
char * name,...) method.
|
|
removeRegexp
|
int removeRegexp (char *regexp);
This method will query the system name server for the list of all
names in the cdevDirectory that match the specified regular
expression. the array of names will be removed from the list
using the remove (int num, char ** names) method and the
result of this operation will be returned.
|
|
|
3.
|
The cdevCollectionRequest Class
|
|
Overview of the
cdevCollection
Request Class
|
The cdevCollectionRequest class is an abstract base class from which other
cdevCollectionRequest objects are derived. It provides a protected constructor and
destructor that are used to initialize its internals, however, the primary mechanism that
is used to obtain a cdevCollectionRequest object is the attachPtr method.
Figure 3:
Object Model of the cdevCollectionRequest Class
|
|
cdevCollectionRequest
attributes:
RESULT_CODE_TAG: int
methods:
cdevCollectionRequest (char **, int, char *, cdevSystem &)
~cdevCollectionRequest (void) :{virtual}
attachPtr (...) :{static} cdevCollectionRequest *
className (void) :{virtual} char *
resultCodeTag (void) :{virtual} int
|
|
|
|
Public Methods of
the
cdevCollection
Request Class
|
|
constructor
|
cdevCollectionRequest( char **devices, int nDevices,
char * msg, cdevSystem & system);
This is the constructor for the cdevCollectionRequest class. It
has the following properties.
|
This method is protected to prevent the direct instantiation
of new cdevCollectionRequests. New instances of the
cdevCollectionRequest objects are created by using the
attachPtr or attachRef method of the cdevRequestObject
class which will call the local attachPtr method to create a
new object if necessary.
The constructor is called by the cdevCollection object and
is provided with a list and count of devices that will be
included in the collection and the message that will be sent
to them.
The cdevSystem reference that is provided is the
cdevSystem instance that will be used to poll, pend and
flush the cdevCollectionRequest object.
|
destructor
|
virtual ~cdevCollectionRequest (void);
This is the destructor for a cdevCollectionRequest object. It has
the following properties.
|
This method is protected to prevent the
cdevCollectionRequest object from being destroyed by the
application. This method should only be called by the
cdevSystem object when the application is terminating.
Because the cdevCollectionRequest object will normally be
referred to as a cdevRequestObject object, this destructor
is virtual to ensure that the 'most senior' destructor is
called first.
|
attachPtr
|
cdevCollectionRequest * attachPtr
( cdevCollection &col, char *msg, cdevSystem &sys);
This method is used by the cdevCollection object to obtain a
new cdevCollectionRequest object.
|
This method will obtain a copy of the device names from
the cdevCollection object and will poll the cdevDirectory
object to determine which service each of them is
associated with.
If the devices are all from a single service, this method will
return a service specific collection request object.
If the devices are from a variety of services, this method will
return a cdevGrpCollectionRequest that contains the
service specific collection request objects.
Device/message combinations that are not associated with
a service will be ignored.
If none of the device/message combinations can be
associated with a service, then an error message will be
generated and NULL will be returned.
|
className
|
char * className (void);
This method returns the name of the class;
"cdevCollectionRequest". If the developer inherits a service
specific cdevCollectionRequest, then this method should not be
altered or overridden.
|
|
resultCodeTag
|
int resultCodetag (void);
This method returns the integer tag that should be used to
insert the result code that was geneterated when the message
was sent to the actual device.
|
|
|
4.
|
The cdevData Class
|
|
Overview of the
cdevData Class
|
The cdevData C++ class is a self describing data object. This class is the primary
mechanism for data interchange within the cdev system. The cdevData object is
capable of storing and retrieving data items of all the primitive data types, as well as
character strings and time stamps. These data items may be scalar or multi-
dimensional arrays.
Figure 4:
Object model of the cdevData class
|
|
class cdevData
methods:
tagC2I (char *, int *) :int
tagI2C (int, char * &) :int
insertTag (int, char *) :void
addTagCallback (cdevTagTableCallback*) :void
delTagCallback (cdevTagTableCallback*) :void
readTagTable (int *&,char **&,int &) :int
operator == (cdevData & data) :int
operator != (cdevData & data) :int
operator = (cdevData &) :cdevData &
operator char (void) :char
operator short (void) :short
operator unsigned short (void) :unsigned short
operator int (void) :int
operator unsigned int (void) :unsigned int
operator long (void) :long
operator unsigned long (void) :unsigned long
operator float (void) :float
operator double (void) :double
asciiDump (FILE *) :void
xdrSize (size_t *, size_t *) :int
xdrExport (char **, size_t *) :int
xdrExport (char *, size_t, size_t):int
xdrImport (char *, size_t) :int
remove (...) :void
changeTag (...) :int
getType (...) :cdevDataTypes
getDim (...) :int
getElems (...) :int
getBounds (...) :int
setBounds (...) :int
insert (...) :int
get (...) :int
find (...) :int
|
|
|
|
Public Methods of
the cdevData
Class
|
|
tagC2I
|
static int tagC2I (char *ctag, int *tag);
Converts a character string tag name to its unique integer
identifier. The function returns CDEV_SUCCESS if the
conversion was successful, otherwise it returns
CDEV_ERROR.
|
|
|