Classes | Public Member Functions | Static Public Member Functions | Private Attributes
GENAPI_NAMESPACE::CNodeMapFactory Class Reference
GenApi_PublicInterface

The node map factory is used for creating node maps from camera description files. More...

#include <NodeMapFactory.h>

List of all members.

Classes

struct  NodeStatistics_t

Public Member Functions

void AddInjectionData (CNodeMapFactory &injectionData)
 Adds a node map factory representing a camera description file to inject.
const GENICAM_NAMESPACE::gcstring ApplyStyleSheet (const GENICAM_NAMESPACE::gcstring &StyleSheetFileName)
 Applies a style sheet to the pre-processed node map.
 CNodeMapFactory ()
 Creates an empty node map factory for assigning a non-empty node map factory later.
 CNodeMapFactory (const CNodeMapFactory &)
 Creates another reference to the node map factory data. No data is copied.
 CNodeMapFactory (EContentType_t FileType, const GENICAM_NAMESPACE::gcstring &FileName, ECacheUsage_t CacheUsage=CacheUsage_Automatic, bool SuppressStringsOnLoad=false)
 Creates the node map factory and simply stores the full path to the provided camera description file data.
 CNodeMapFactory (EContentType_t ContentType, const void *pData, size_t DataSize, ECacheUsage_t CacheUsage=CacheUsage_Automatic, bool SuppressStringsOnLoad=false)
 Creates the node map factory and simply stores the pointer and the size of the provided camera description file data.
 CNodeMapFactory (const GENICAM_NAMESPACE::gcstring &XmlData, ECacheUsage_t CacheUsage=CacheUsage_Automatic, bool SuppressStringsOnLoad=false)
 Creates the node map factory and copies the provided camera description file string.
INodeMap * CreateNodeMap (const GENICAM_NAMESPACE::gcstring &DeviceName="Device", bool DoReleaseCameraDescriptionFileData=true)
 Creates a node map from the preprocessed memory internal representation of the camera description file(s).
INodeMap * CreateNodeMap (CLock &UserProvidedLock, const GENICAM_NAMESPACE::gcstring &DeviceName="Device", bool DoReleaseCameraDescriptionFileData=true)
 Creates a node map from the preprocessed memory internal representation of the camera description file(s).
CNodeMapFactory ExtractSubtree (const GENICAM_NAMESPACE::gcstring &SubTreeRootNodeName, bool doRenameToRoot=false)
 The name of the node that represents the root of the subtree that shall be extracted.
void GetNodeStatistics (NodeStatistics_t &NodeStatistics)
void GetSupportedSchemaVersions (GENICAM_NAMESPACE::gcstring_vector &SchemaVersions) const
bool IsCameraDescriptionFileDataReleased () const
 Can be used to check whether the ReleaseCameraDescriptionFileData() processing step has been performed.
bool IsEmpty () const
 Returns true if nothing is loaded (IsLoaded()) and no source data is available, e.g. when the node map factory has been created with the default constructor.
bool IsLoaded () const
 Can be used to check whether the LoadAndInject() processing step has been performed. Returns true if IsPreprocessed() returns true (Preprocessed Data has been loaded from cache).
bool IsPreprocessed () const
 Can be used to check whether the Preprocess() processing step has been performed.
void LoadAndInject ()
 Advanced: Loads, Parses, and Injects the camera description files recursively. The result is a memory internal representation of the camera description file(s), the CNodeDataMap (not part of the public interface).
CNodeMapFactory & operator= (const CNodeMapFactory &)
 Creates another reference to the assigned node map factory data. Destroys the "overwritten" node map factory data if all references to the data have been released.
void Preprocess ()
 Advanced: Creates the preprocessed memory internal representation of the camera description file(s), the CNodeDataMap (not part of the public interface).
void ReleaseCameraDescriptionFileData ()
 Advanced: Releases any in constructors provided camera description file data buffers or files.
GENICAM_NAMESPACE::gcstring ToString () const
 Outputs the pre-processed node map in string form (for debug purpose)
GENICAM_NAMESPACE::gcstring ToXml () const
 Outputs the pre-processed node map in XML form (mainly for debug purpose)
virtual ~CNodeMapFactory ()
 Destroys the node map factory data if all references to the data have been released.

Static Public Member Functions

static bool ClearCache ()
 Deletes all preprocessed camera description files from the cache.
static INodeMap * CreateEmptyNodeMap ()
 Creates an empty node map usable as placeholder, e.g. if certain features are not supported by a module.
static CNodeDataMap * CreateNodeDataFromNodeMap (INodeMap *pNodeMap)

Private Attributes

CNodeMapFactoryImpl * m_pImpl

Detailed Description

The node map factory is used for creating node maps from camera description files.

Examples
    // Simple node map creation from buffer, downloaded from a device for instance.
    CNodeMapFactory cameraNodeMapFactory( ContentType_ZippedXml, buffer, bufferSize);
    
    // Create the node map. The node map can be destroyed using the IDestroy interface later.
    INodeMap* pNodeMap = cameraNodeMapFactory.CreateNodeMap();
    // The next step is attaching the device port (not shown).

    // Node map creation with injecting additional xml fragments.
    CNodeMapFactory cameraNodeMapFactory( ContentType_Xml, buffer, bufferSize);
    cameraParameters.AddInjectionData( CNodeMapFactory(ContentType_Xml, filename1));
    cameraParameters.AddInjectionData( CNodeMapFactory(ContentType_Xml, filename2));

    // Create the node map. The node map can be destroyed using the IDestroy interface later.
    INodeMap* pNodeMap = cameraNodeMapFactory.CreateNodeMap();
    // The next step is attaching the device port (not shown).

    // Node map creation and additional extraction of a category subtree.
    CNodeMapFactory cameraNodeMapFactory( ContentType_Xml, buffer, bufferSize);
    // Extract a subtree for later chunk parsing.
    CNodeMapFactory chunkDataNodeMapFactory = cameraParameters.ExtractSubtree("ChunkData");

    // Create the node map. The node map can be destroyed using the IDestroy interface later.
    INodeMap* pNodeMap = cameraParameters.CreateNodeMap();
    // The next step is attaching the device port (not shown).

    // Node map creation with injecting additional xml fragments and additional extraction of a category subtree.
    CNodeMapFactory cameraNodeMapFactory( ContentType_Xml, buffer, bufferSize);
    cameraParameters.AddInjectionData( CNodeMapFactory(ContentType_Xml, filename1));
    cameraParameters.AddInjectionData( CNodeMapFactory(ContentType_Xml, filename2));
    CNodeMapFactory chunkDataNodeMapFactory = cameraNodeMapFactory.ExtractSubtree("ChunkData");

    // Create the node map. The node map can be destroyed using the IDestroy interface later.
    INodeMap* pNodeMap = cameraNodeMapFactory.CreateNodeMap();
    // The next step is attaching the device port (not shown).

    // A node map factory can create multiple node maps from the provided camera description file(s).
    for(int i = 0; i < 20; ++i)
    {
        INodeMap* pNodeMapChunks = chunkDataNodeMapFactory.CreateNodeMap();
        //...
    }
Attention:
The is CNodeMapFactory not thread-safe.
You need to take care when camera description file data can be actually be freed, see method documentation of the node map factory for more detail.

Definition at line 137 of file NodeMapFactory.h.

Constructor & Destructor Documentation

GENAPI_NAMESPACE::CNodeMapFactory::CNodeMapFactory ( )

Creates an empty node map factory for assigning a non-empty node map factory later.

virtual GENAPI_NAMESPACE::CNodeMapFactory::~CNodeMapFactory ( ) [virtual]

Destroys the node map factory data if all references to the data have been released.

GENAPI_NAMESPACE::CNodeMapFactory::CNodeMapFactory ( const CNodeMapFactory &  )

Creates another reference to the node map factory data. No data is copied.

GENAPI_NAMESPACE::CNodeMapFactory::CNodeMapFactory ( EContentType_t  FileType,
const GENICAM_NAMESPACE::gcstring &  FileName,
ECacheUsage_t  CacheUsage = CacheUsage_Automatic,
bool  SuppressStringsOnLoad = false 
)

Creates the node map factory and simply stores the full path to the provided camera description file data.

Parameters:
[in]FileTypeDefines how the camera description file is stored, e.g. as zipped XML text.
[in]FileNameThe full path of the camera description file to process.
[in]CacheUsageDefines if and how to use the cache for preprocessed camera description files.
[in]SuppressStringsOnLoadSuppresses loading strings that are not needed for most use cases, e.g. node tooltip or description, for reducing the memory footprint.

Throws an invalid argument exception if FileName is empty. Throws if environment variables in FileName cannot be resolved.

Attention:
The given file must be readable until the camera description file data has been released. The IsCameraDescriptionFileDataReleased() method can be used to check if releasing has been done.
GENAPI_NAMESPACE::CNodeMapFactory::CNodeMapFactory ( EContentType_t  ContentType,
const void *  pData,
size_t  DataSize,
ECacheUsage_t  CacheUsage = CacheUsage_Automatic,
bool  SuppressStringsOnLoad = false 
)

Creates the node map factory and simply stores the pointer and the size of the provided camera description file data.

Parameters:
[in]ContentTypeDefines how the camera description file is stored, e.g. as zipped XML text.
[in]pDataThe pointer to the camera description file data.
[in]DataSizeThe size of the camera description file data.
[in]CacheUsageDefines if and how to use the cache for preprocessed camera description files.
[in]SuppressStringsOnLoadSuppresses loading strings that are not needed for most use cases, e.g. node tooltip or description, for reducing the memory footprint.

Throws an invalid argument exception if pData is NULL or DataSize is 0.

Attention:
The given buffer must not be freed or changed until the camera description file data has been released. The IsCameraDescriptionFileDataReleased() method can be used to check if releasing has been done.
GENAPI_NAMESPACE::CNodeMapFactory::CNodeMapFactory ( const GENICAM_NAMESPACE::gcstring &  XmlData,
ECacheUsage_t  CacheUsage = CacheUsage_Automatic,
bool  SuppressStringsOnLoad = false 
)

Creates the node map factory and copies the provided camera description file string.

Parameters:
[in]XmlDataThe camera description file data as XML text. The provided text is copied. You can use the overloaded constructor accepting a buffer to avoid that. 
                                gcstring cdfData;
                                //... fill cdfData ...
                                CNodeMapFactory factory(ContentType_Xml, cfdData.c_str(), cfdData.size());
                                // Create the node map. The node map can be destroyed using the IDestroy interface later.
                                INodeMap* pNodeMap = factory.CreateNodeMap();
                                // The next step is attaching the device port (not shown).
[in]CacheUsageDefines if and how to use the cache for preprocessed camera description files.
[in]SuppressStringsOnLoadSuppresses loading strings that are not needed for most use cases, e.g. node tooltip or description, for reducing the memory footprint.

Throws an invalid argument exception if XmlData is empty.

Member Function Documentation

void GENAPI_NAMESPACE::CNodeMapFactory::AddInjectionData ( CNodeMapFactory &  injectionData)

Adds a node map factory representing a camera description file to inject.

Parameters:
[in]injectionDataA node map factory representing a camera description file to inject.

The injected files are injected in the order they are added. InjectionData must not be preprocessed. The IsPreprocessed() method can be used to check if preprocessing has been done before. The cache usage of injection data is ignored.

const GENICAM_NAMESPACE::gcstring GENAPI_NAMESPACE::CNodeMapFactory::ApplyStyleSheet ( const GENICAM_NAMESPACE::gcstring &  StyleSheetFileName)

Applies a style sheet to the pre-processed node map.

static bool GENAPI_NAMESPACE::CNodeMapFactory::ClearCache ( ) [static]

Deletes all preprocessed camera description files from the cache.

static INodeMap* GENAPI_NAMESPACE::CNodeMapFactory::CreateEmptyNodeMap ( ) [static]

Creates an empty node map usable as placeholder, e.g. if certain features are not supported by a module.

static CNodeDataMap* GENAPI_NAMESPACE::CNodeMapFactory::CreateNodeDataFromNodeMap ( INodeMap *  pNodeMap) [static]
INodeMap* GENAPI_NAMESPACE::CNodeMapFactory::CreateNodeMap ( const GENICAM_NAMESPACE::gcstring &  DeviceName = "Device",
bool  DoReleaseCameraDescriptionFileData = true 
)

Creates a node map from the preprocessed memory internal representation of the camera description file(s).

Preprocess() is automatically called if needed. The preprocess step can be omitted by the factory depending on the cache mode setting when a cache file is available, then the cache file is read and converted directly into a node map. ReleaseCameraDescriptionFileData() is called if DoReleaseCameraDescriptionFileData is true. This method can be called multiple times to create multiple instances of a node map.

INodeMap* GENAPI_NAMESPACE::CNodeMapFactory::CreateNodeMap ( CLock &  UserProvidedLock,
const GENICAM_NAMESPACE::gcstring &  DeviceName = "Device",
bool  DoReleaseCameraDescriptionFileData = true 
)

Creates a node map from the preprocessed memory internal representation of the camera description file(s).

Preprocess() is automatically called if needed. The preprocess step can be omitted by the factory depending on the cache mode setting when a cache file is available, then the cache file is read and converted directly into a node map. ReleaseCameraDescriptionFileData() is called if DoReleaseCameraDescriptionFileData is true. This method can be called multiple times to create multiple instances of a node map. This method allows to provide an external lock to avoid using too many locks in an application.

Attention:
The provided lock must not be destroyed before the created node map.
CNodeMapFactory GENAPI_NAMESPACE::CNodeMapFactory::ExtractSubtree ( const GENICAM_NAMESPACE::gcstring &  SubTreeRootNodeName,
bool  doRenameToRoot = false 
)

The name of the node that represents the root of the subtree that shall be extracted.

Parameters:
[in]SubTreeRootNodeNameThe root of the branch to extract, e.g. "ChunkData".
[in]doRenameToRootRenames the extracted subtree root node SubTreeRootNodeName to "Root", sets the IsFeature property. Preprocess() is automatically called if needed to create the memory internal representation of the camera description file(s). The preprocessed result can be read from the cache or written to the cache in this step. This depends on the availability of a cache and the used CacheUsage setting.
void GENAPI_NAMESPACE::CNodeMapFactory::GetNodeStatistics ( NodeStatistics_t &  NodeStatistics)
void GENAPI_NAMESPACE::CNodeMapFactory::GetSupportedSchemaVersions ( GENICAM_NAMESPACE::gcstring_vector &  SchemaVersions) const

Each list entry is a string with the format "{Major}.{Minor}" were {Major} and {Minor} are integers Example: {"1.1", "1.2"} indicates that the schema v1.1 and v1.2 are supported. The SubMinor version number is not given since it is for fully compatible bug fixes only

bool GENAPI_NAMESPACE::CNodeMapFactory::IsCameraDescriptionFileDataReleased ( ) const

Can be used to check whether the ReleaseCameraDescriptionFileData() processing step has been performed.

bool GENAPI_NAMESPACE::CNodeMapFactory::IsEmpty ( ) const

Returns true if nothing is loaded (IsLoaded()) and no source data is available, e.g. when the node map factory has been created with the default constructor.

bool GENAPI_NAMESPACE::CNodeMapFactory::IsLoaded ( ) const

Can be used to check whether the LoadAndInject() processing step has been performed. Returns true if IsPreprocessed() returns true (Preprocessed Data has been loaded from cache).

bool GENAPI_NAMESPACE::CNodeMapFactory::IsPreprocessed ( ) const

Can be used to check whether the Preprocess() processing step has been performed.

void GENAPI_NAMESPACE::CNodeMapFactory::LoadAndInject ( )

Advanced: Loads, Parses, and Injects the camera description files recursively. The result is a memory internal representation of the camera description file(s), the CNodeDataMap (not part of the public interface).

This step is usually done automatically. Prevents cache read if called manually.

CNodeMapFactory& GENAPI_NAMESPACE::CNodeMapFactory::operator= ( const CNodeMapFactory &  )

Creates another reference to the assigned node map factory data. Destroys the "overwritten" node map factory data if all references to the data have been released.

void GENAPI_NAMESPACE::CNodeMapFactory::Preprocess ( )

Advanced: Creates the preprocessed memory internal representation of the camera description file(s), the CNodeDataMap (not part of the public interface).

This step is usually done automatically. Preprocessed data can be read from the cache or written to the cache in this step. This depends on the availability of a cache and the used CacheUsage setting. By calling this method directly direct cache load is suppressed, see CreateNodeMap() for more information.

void GENAPI_NAMESPACE::CNodeMapFactory::ReleaseCameraDescriptionFileData ( )

Advanced: Releases any in constructors provided camera description file data buffers or files.

This step is usually done automatically. All references to added injection data are dropped in this step to free the data. After this step any in constructors provided buffers can be freed or any in constructors given files can be deleted.

GENICAM_NAMESPACE::gcstring GENAPI_NAMESPACE::CNodeMapFactory::ToString ( ) const

Outputs the pre-processed node map in string form (for debug purpose)

GENICAM_NAMESPACE::gcstring GENAPI_NAMESPACE::CNodeMapFactory::ToXml ( ) const

Outputs the pre-processed node map in XML form (mainly for debug purpose)

Member Data Documentation

CNodeMapFactoryImpl* GENAPI_NAMESPACE::CNodeMapFactory::m_pImpl [private]

Definition at line 327 of file NodeMapFactory.h.

The documentation for this class was generated from the following file:

rc_visard_driver
Author(s): Heiko Hirschmueller , Christian Emmerich , Felix Ruess
autogenerated on Thu Jun 6 2019 20:43:11