NAME
-
vsQueryTypeNameAccessorCls - Query container functionality for parameter extraction
INHERITS FROM
-
vsQueryTypeBaseCls
HEADER FILE
-
#include <vizserver/vsQueryType.h>
PUBLIC METHOD SUMMARY
virtual vsStatus getParam ( |
QueryTypeEnum name, vsParamTypeCls*& param) const = 0; |
INHERITED PUBLIC METHODS
Inherited from vsQueryTypeBaseCls
CLASS DESCRIPTION
-
The compression API passes several different arguments to compressors in
the form of query containers. Query containers are objects that contain
other objects embedded inside of them. These objects can be extracted by
using the following interface.
-
The objects that can be extracted are all of type
vsParamTypeCls. Some objects such as vsFrameInfo
are also of type vsQueryTypeNameAccessorCls and are also
query containers for other objects.
Identifying the supported query interface
-
As of Vizserver 1.3, only the name accessor query type is supported.
Therefore are embedded parameters can be extracted by passing in a
enumerated value that refers to the parameter's name.
-
Other interfaces may be supported in the future, however in order to
identify what interface is used by the query object, a call to
getTypeName() can be made. This will return the value of
the query type in question. After identifying the query type, the
correct parameter names can be passed to the getParam() function
to extract the parameters.
-
The following are the enumerated values for various query container types:
struct vsQueryTypes {
enum Base {
// These are the base accessor types for query containers.
// NameAccessor and BaseAccessor are the only supported ones
// at the moment.
BaseAccessor = 0x00000000,
NameAccessor = 0x00000001,
ArrayAccessor = 0x00000002,
NameArrayAccessor = 0x00000003
};
};
struct vsCmprQueryTypes {
// These are the compression related query types. The class
// names for the actual object are simple found be prepending
// a "vs" in front of the type name.
enum QueryParams {
NoQueryParam = 0x00000000,
FrameInfo = 0x00001010,
FrameData = 0x00001011
};
enum QueryMessages {
NoQueryMessage = 0x00000000,
StreamMessage = 0x00001020
};
};
struct vsParamTypes {
enum Base {
NoParam = 0x00000000,
CmprParam = 0x00001101,
CmprQueryParam = 0x00001102,
CmprQueryMessage = 0x00001103
};
};
Extracting parameters
-
With the name accessor query type, extracting parameters can be simply
done by refering to the parameter needed with the correct enum value.
Here are a list of parameter enum values:
struct vsCmprParamTypes {
//These values are used by vsCmprParamArg. Use these when
//extracting parameters from this object.
enum AllParams {
NoParam = 0x00000000,
FieldInfoParam = 0x00001101,
FieldDataParam = 0x00001102,
FrameInfoParam = 0x00001010,
FrameDataParam = 0x00001011,
StreamMessageParam = 0x00001020
};
//Objects such as vsFrameInfo, vsStreamMessgae, and vsCmprInputQueryArg
//use these enum values. Refer to these values when attempting queries.
enum FieldParams {
NoFieldParam = 0x00000000,
FieldInfo = 0x00001101,
FieldData = 0x00001102
};
enum QueryParams {
NoQueryParam = 0x00000000,
FrameInfo = 0x00001010,
FrameData = 0x00001011
};
enum QueryMessages {
NoQueryMessage = 0x00000000,
StreamMessage = 0x00001020
};
};
-
A call to getParam() with the correct enum value and a pointer
to the parameter will extract the parameter and the pointer will point to
the parameter object. It is important to note that the parameter pointer
must be downcasted to vsParamTypeCls*& before passing it to the
function.
-
Also as a supporting function, isParamPresent() can be used
prior to a call to getParam() to find out if the query container
holds the requested parameter.
-
For example we have a vsCmprInputQueryArg object that is passed into
compress function from vsCompressor module. We need to
extract the vsFrameInfo and vsFrameData objects
from it. Here is how we can use the above concepts:
#define (vsParamTypeCls*&) PARAMCAST
size_t
NOPCompressor::compress(const vsCmprInputQueryArg& input,
vsCmprOutputQueryArg& output)
{
vsFrameInfo* frameInfo;
vsFrameData* frameData;
... other declarations ...
vsStatus stsFrInfo = input.getParam(vsCmprQueryTypes::FrameInfo,
PARAMCAST frameInfo);
vsStatus stsFrData = input.getParam(vsCmprQueryTypes::FrameData,
PARAMCAST frameData);
if ((stsFrInfo != vsErrNone) ||
(stsFrData != vsErrNone)) {
fprintf(stderr, "nopCompressor - couldn't retrieve FrameInfo "
"and FrameData parameters\n");
return 0;
}
...other code for compression...
}
Error codes
-
A call to getParam() can sometimes fail. In cases of
failure, the return type of vsStatus can be checked for the cause.
-
Two failure codes can be return as of Vizserver 1.3, vsErrNoEntry and
vsErrBadCast. The first will occur when a requested parameter type
is not found within the query container object. The second error can
occur when the returned parameter cannot safely be casted to the pointer
passed with getParam(). Failures must be anticipated by the
module writer.
-
A success is indicated by vsErrNone.
METHOD DESCRIPTIONS
~vsQueryTypeNameAccessorCls()
virtual ~vsQueryTypeNameAccessorCls ( |
); |
-
Object destructor
getParam()
virtual vsStatus getParam ( |
QueryTypeEnum name, vsParamTypeCls*& param) const = 0; |
-
Function for extracting parameter from the query container.
-
Argument name will be of the appropriate type for the query
container. For example vsFrameInfo will only accept
parameter types of vsFieldTypes::Fields while
vsCmprParamArg will only accept types of
vsCmprParamTypes::AllParams.
-
Argument param will be a pointer of the parameter type. If the
function returns successfully, the pointer will point to the extracted
parameter.
getTypeName()
virtual QueryClass getTypeName ( |
) const = 0; |
-
Returns the query type name of the container class. The
return type will be of the enum type for the associated query class.
For example, vsFrameInfo will be of type
vsCmprQueryTypes::QueryParams while vsStreamMessage
will be of type vsCmpreQueryTypes::QueryMessages.
isParamPresent()
virtual vsBool isParamPresent ( |
QueryTypeEnum name) const = 0; |
-
Returns TRUE is the parameter of type name is contained within
this container. Otherwise the return value is FALSE.
SEE ALSO
-
vsCompressor, vsFrameData, vsFrameInfo, vsParamTypeCls, vsQueryTypeBaseCls, vsQueryTypeNameAccessorCls, vsStreamMessage