//------------------------------------------------------------------------------ // Basler pylon SDK // Copyright (c) 2018-2021 Basler AG // http://www.baslerweb.com //------------------------------------------------------------------------------ /*! \file \brief Contains the class CParameter used to simplify access to %GenApi parameters. */ #ifndef INCLUDED_BASLER_PYLON_CPARAMETER_H #define INCLUDED_BASLER_PYLON_CPARAMETER_H #pragma once #include #include #ifdef _MSC_VER # pragma pack(push, PYLON_PACKING) #endif /* _MSC_VER */ #ifdef _MSC_VER # pragma warning( push ) # pragma warning( disable : 4275 ) // Class needs to have a dll interface to be used by clients of the class. # pragma warning( disable : 4250 ) // warning C4250: 'Pylon::CXYZParameter': inherits 'Pylon::CParameter::Pylon::CParameter::ZYX' via dominance #endif namespace Pylon { /// Lists possible parameter info values. enum EParameterInfo { /// The identifier of a parameter. It can be used to access the node via a node map using GenApi::INodeMap::GetNode() /// or to access the value of an enumeration parameter using CEnumParameter::GetEntryByNameAsParameter(). ParameterInfo_Name, /// The name of a parameter or an enumeration value that can be used for display in a user interface. ParameterInfo_DisplayName, /// The short description of a parameter or an enumeration value. ParameterInfo_ToolTip, /// The long description of a parameter or an enumeration value. ParameterInfo_Description }; /*! \brief Extends the GenApi::IValue interface with convenience methods. */ interface IValueEx : virtual public GenApi::IValue { /*! \brief Indicates whether the parameter is readable. \error Does not throw C++ exceptions. \return Returns true if the parameter is readable. */ virtual bool IsReadable() const = 0; /*! \brief Indicates whether the parameter is writable. \error Does not throw C++ exceptions. \return Returns true if the parameter is writable. */ virtual bool IsWritable() const = 0; /*! \brief Indicates whether a node is attached. \return Returns true if a node is attached. \error Does not throw C++ exceptions. */ virtual bool IsValid() const = 0; /*! \brief Gets the parameter information. \param[in] info The type information to return. \return Returns the parameter information. \threading The method accesses the parameter multiple times. These accesses are not synchronized by a lock. \error Throws an exception if no node is attached. Can throw exceptions if the retrieval of the information fails. */ virtual String_t GetInfo( EParameterInfo info ) = 0; /*! \brief Gets the parameter information if the parameter is attached to a node. See IsValid(). \param[in] info The type information to return. \brief Otherwise returns the default information. This method is useful if you want to display parameter information and handle the case that some parameters are not available for a device. \return Returns the parameter information if the parameter is attached to a node. Otherwise returns the default information. \param[in] defaultInfo The default information returned if the parameter is not attached to a node. \threading The method accesses the parameter multiple times. These accesses are not synchronized by a lock. \error Can throw exceptions if the retrieval of the information fails. */ virtual String_t GetInfoOrDefault( EParameterInfo info, const String_t defaultInfo ) = 0; /*! \brief Gets the parameter value as string if the parameter is readable. \brief Otherwise returns the default value. \return Returns the parameter value if the parameter is readable. Otherwise returns the default value. \param[in] defaultValue The default value returned if the parameter is not readable. \threading The method accesses the parameter multiple times. These accesses are not synchronized by a lock. \error Can throw exceptions if reading the value fails. */ virtual String_t ToStringOrDefault( const String_t& defaultValue ) = 0; }; /*! \brief CParameter class used to simplify access to %GenApi parameters. */ class PYLONBASE_API CParameter : virtual public IValueEx { public: /*! \brief Creates an empty CParameter object. \error Does not throw C++ exceptions. */ CParameter(); /*! \brief Creates a CParameter object and attaches it to a node, typically retrieved for a nodemap calling GetNode(). \param[in] pNode The node to attach. \post \error Does not throw C++ exceptions. */ explicit CParameter( GenApi::INode* pNode ); /*! \brief Creates a CParameter object and attaches it to a node of a matching type. \param[in] pValue The node to attach. \post The parameter object must not be used to access the node's functionality if the source of the attached \c pValue has been destroyed. In this case, call Release() or attach a new node. \error Does not throw C++ exceptions. */ explicit CParameter( GenApi::IValue* pValue ); /*! \brief Creates a CParameter object and attaches it to a node retrieved from the provided node map. \param[in] pNodeMap The node map. The source of the parameter. \param[in] pName The name of the parameter to attach. \post \error The call to GenApi::INodeMap::GetNode can throw C++ exceptions. */ CParameter( GenApi::INodeMap* pNodeMap, const char* pName ); /*! \brief Creates a CParameter object and attaches it to a node retrieved from the provided node map. \param[in] nodeMap The node map. The source of the parameter. \param[in] pName The name of the parameter to attach. \post \error The call to GenApi::INodeMap::GetNode can throw C++ exceptions. */ CParameter( GenApi::INodeMap& nodeMap, const char* pName ); /*! \brief Copies a CParameter object. \param[in] rhs The object to copy. \error Does not throw C++ exceptions. */ CParameter( const CParameter& rhs ); /*! \brief Destroys the CParameter object. Does not access the attached node. \error Does not throw C++ exceptions. */ virtual ~CParameter(); /*! \brief Attaches a node retrieved from the provided node map. \param[in] pNodeMap The node map. The source of the parameter. \param[in] pName The name of the parameter to attach. \return Returns true if the node has been attached. \post \error The call to GenApi::INodeMap::GetNode can throw C++ exceptions. */ virtual bool Attach( GenApi::INodeMap* pNodeMap, const char* pName ); /*! \brief Attaches a node retrieved from the provided node map. \param[in] nodeMap The node map. The source of the parameter. \param[in] pName The name of the parameter to attach. \return Returns true if the node has been attached. \post \error The call to GenApi::INodeMap::GetNode can throw C++ exceptions. */ virtual bool Attach( GenApi::INodeMap& nodeMap, const char* pName ); /*! \brief Attaches a node, typically retrieved for a nodemap calling GetNode(). \param[in] pNode The node to assign. \return Returns true if the node has been attached. \post \error Does not throw C++ exceptions. */ virtual bool Attach( GenApi::INode* pNode ); /*! \brief Assigns a node of the same type to the parameter object. \param[in] pValue The node to assign. \return Returns true if the node has been attached. \error Does not throw C++ exceptions. */ virtual bool Attach( GenApi::IValue* pValue ); /*! \brief Assigns a CParameter object. \param[in] rhs The object to assign. \error Does not throw C++ exceptions. */ CParameter& operator=( const CParameter& rhs ); /*! \brief Returns true if the same nodes are attached or both parameters are empty. \param[in] rhs The object to compare to. \return Returns true if the same nodes are attached or both parameters are empty. \error Does not throw C++ exceptions. */ virtual bool Equals( const CParameter& rhs ) const; /*! \brief Returns true if the attached node pointer is equal. \param[in] pNode The node to compare to. \return Returns true if the attached node pointer is equal. \error Does not throw C++ exceptions. */ virtual bool Equals( const GenApi::INode* pNode ) const; /*! \brief Returns true if the attached node pointer is equal. \param[in] pValue The node to compare to. \return Returns true if the attached node pointer is equal. \error Does not throw C++ exceptions. */ virtual bool Equals( const GenApi::IValue* pValue ) const; /*! \brief Releases the attached node. \error Does not throw C++ exceptions. */ virtual void Release(); // Implements GenApi::IBase virtual GenApi::EAccessMode GetAccessMode() const; // Implements GenApi::IValue virtual GenApi::INode* GetNode(); // Implements GenApi::IValue virtual GenICam::gcstring ToString( bool verify = false, bool ignoreCache = false ); // Implements GenApi::IValue virtual void FromString( const GenICam::gcstring& valueStr, bool verify = true ); // Implements GenApi::IValue virtual bool IsValueCacheValid() const; // Implements IValueEx virtual bool IsReadable() const; // Implements IValueEx virtual bool IsWritable() const; // Implements IValueEx virtual bool IsValid() const; // Implements IValueEx virtual String_t GetInfo( EParameterInfo info ); // Implements IValueEx virtual String_t GetInfoOrDefault( EParameterInfo info, const String_t defaultInfo ); // Implements IValueEx virtual String_t ToStringOrDefault( const String_t& defaultValue ); protected: GenApi::IValue* m_pValue; }; } #ifdef _MSC_VER # pragma warning( pop ) #endif #ifdef _MSC_VER # pragma pack(pop) #endif /* _MSC_VER */ #endif /* INCLUDED_BASLER_PYLON_CPARAMETER_H */