OpenGL Vizserver Reference Page


NAME
vsQueryTypeNameAccessorCls - Query container functionality for parameter extraction

INHERITS FROM
vsQueryTypeBaseCls

HEADER FILE
#include <vizserver/vsQueryType.h>

PUBLIC METHOD SUMMARY
virtual QueryClass getTypeName (  ) const = 0;
virtual vsStatus getParam ( QueryTypeEnum name, vsParamTypeCls*& param) const = 0;
virtual vsBool isParamPresent ( QueryTypeEnum name) const = 0;
virtual ~vsQueryTypeNameAccessorCls (  );

INHERITED PUBLIC METHODS

   Inherited from vsQueryTypeBaseCls
virtual vsBool isQueryTypeSupported ( vsQueryTypes::Base name) const;

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