Cross Point


IParameter Interface Reference

Inheritance diagram for IParameter:

IXMLBase IEventBase List of all members.

Detailed Description

This interface is used for setting/retrieving parameters.

All parameters should first be retrieved using the IParameterDatabase::FindParameter method, or using the IParameterDatabase::Parameters collection. This will set all information of the parameter object. Next the parameter can be changed through this interface. Writing back the changes to the reader should be done with the Save method.

For details about the parameter information, see method and property details.

Note that:


Public Member Functions

HRESULT ParameterDatabase ([out, retval] IParameterDatabase **ppintfParameterDatabase)
 Returns the parameter database this parameter belongs to.

HRESULT Number ([out, retval] ENVP *pENVP)
 Returns the number of the parameter.

HRESULT Description ([out, retval] BSTR *pbstrDescription)
 Returns a description of this parameter (only if a correct language dll can be found).

HRESULT GetDescription ([in, defaultvalue(1)] VARIANT_BOOL LongDescription,[out, retval] BSTR *pbstrDescription)
 Returns a long or short description of this parameter.

HRESULT Value ([out, retval] VARIANT *pvtValue)
 Returns the current value of this parameter.

HRESULT Value ([in] VARIANT NewValue)
 Sets the new value of this parameter.

HRESULT ValueDescription ([out, retval] BSTR *pbstrDescription)
 Returns a description of the current value of this parameter (in readable format).

HRESULT Type ([out, retval] ENVPType *peType)
 Returns the type of the parameter.

HRESULT Size ([out, retval] short *psSize)
 Returns the size of this parameter value.

HRESULT Min ([out, retval] VARIANT *pvtMin)
 Returns the minimum value of this parameter.

HRESULT Max ([out, retval] VARIANT *pvtMax)
 Returns the maximum value of this parameter.

HRESULT Default ([out, retval] VARIANT *pvtDefault)
 Returns the default factory setting of this parameter.

HRESULT IsReadOnly ([out, retval] VARIANT_BOOL *pfIsReadOnly)
 Returns true if this parameter is a read-only parameter.

HRESULT IsPassword ([out, retval] VARIANT_BOOL *pfIsPassword)
 Returns true if this parameter is a password parameter.

HRESULT IsModified ([out, retval] VARIANT_BOOL *pfIsModified)
 Returns true if the value of this parameter is modified.

HRESULT CanBeChangedByUser ([out, retval] VARIANT_BOOL *pfIsUserLevel)
 Returns true if this parameter is accessable at user level.

HRESULT CanBeChangedByInstaller ([out, retval] VARIANT_BOOL *pfIsInstaller)
 Returns true if this parameter is accessable at installer level.

HRESULT IsResetRequired ([out, retval] VARIANT_BOOL *pfIsResetRequired)
 Returns true if this parameter requires a restart to be effective after it has been changed.

HRESULT AdditionalInfoPresent ([out, retval] VARIANT_BOOL *pfIsAdditionalInfo)
 Returns true if this parameter contains additional information (min/max and default information).

HRESULT Save ([in, defaultvalue(0xffff)] VARIANT_BOOL fDisableRFID,[out, retval] VARIANT_BOOL *pfSucceeded)
 Save the new parameter settings into the reader.

HRESULT Refresh ()
 Refresh this parameters value.


Member Function Documentation

IParameter::ParameterDatabase [out, retval] IParameterDatabase **  ppintfParameterDatabase  ) 
 

Returns the parameter database this parameter belongs to.

Parameters:
ppintfParameterDatabase Receives the parameter database object.
Precondition:
ppintfParameterDatabase is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
IParameterDatabase

IParameter::Number [out, retval] ENVP peNVP  ) 
 

Returns the number of the parameter.

Parameters:
peNVP Receives the current parameter number.
Precondition:
peNVP is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ENVP, Description

IParameter::Description [out, retval] BSTR *  pbstrDescription  ) 
 

Returns a description of this parameter (only if a correct language dll can be found).

This property will receive the long description of this parameter. See GetDescription for more information.

Parameters:
pbstrDescription Receives the description.
Precondition:
pbstrDescription is not NULL.
See also:
GetDescription, ValueDescription

IParameter::GetDescription [in, defaultvalue(1)] VARIANT_BOOL  fLongDescription,
[out, retval] BSTR *  pbstrDescription
 

Returns a long or short description of this parameter.

If this parameter is for instance nvpDoorOpenTime, the long english description will return: "Door open time, in seconds", the short description will be "Open time". The description is loaded from a resource dll (only if the correct language dll can be found). Note that when for instance a Dutch windows version is installed, a dutch description will be returned.

Parameters:
fLongDescription If set to true, the long description is returned, else a short description is returned.
pbstrDescription Receives the description.
Precondition:
pbstrDescription is not NULL.
See also:
Description, ValueDescription

IParameter::Value [out, retval] VARIANT *  pvtValue  ) 
 

Returns the current value of this parameter.

This property may return three different type:

  • When this parameter contains a date (for instance the nvpTimezoneNightToDayMarker parameter), a date is returned. Note that only the time-part of the returned date is applicable for the markers (the day-part will always be 1-1-2001).
  • When this parameter contains a string (the nvpDeviceName parameter), a string value is returned.
  • For all other parameters the value is returned (either VT_UI1, VT_UI2 or VT_I4 format, depending on the Size).
Parameters:
pvtValue Receives the current value of the parameter.
Precondition:
pvtValue is not NULL.
Note:
When the IsPassword property is true, the value returned here should not be displayed to the user since it compromizes security.
See also:
ValueDescription, Min, Max, Default, IsPassword, Type, Size

IParameter::Value [in] VARIANT  vtNewValue  ) 
 

Sets the new value of this parameter.

If the parameter contains AdditionalInfoPresent, Min and Max can be used to determine the boundaries of this parameter. The Default property holds the factory default value for this parameter.

Parameters:
vtNewValue The new value for this parameter.
See also:
ValueDescription, Min, Max, Default, IsPassword, Type, Size

IParameter::ValueDescription [out, retval] BSTR *  pbstrDescription  ) 
 

Returns a description of the current value of this parameter (in readable format).

If this parameter is for instance nvpTimezoneWeekscheme, and the value is for instance 7, the english description will return the string: "Monday, Tuesday, Wednesday" (or something similar).

The description is loaded from a resource dll (only if the correct language dll can be found). Note that when for instance a Dutch windows version is installed, a dutch description will be returned.

If this parameter contains a password (see IsPassword), the following string will always be returned: "*********".

Parameters:
pbstrDescription Receives a description of the current value of this parameter.
Precondition:
pbstrDescription is not NULL.
See also:
IsPassword, Description, GetDescription

IParameter::Type [out, retval] ENVPType peType  ) 
 

Returns the type of the parameter.

Parameters:
peType Receives the current parameter type.
Precondition:
peType is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
ENVPType, Size

IParameter::Size [out, retval] short *  psSize  ) 
 

Returns the size of this parameter value.

For number parameters, this property returns the size in bytes of the number (1 for a BYTE, 2 for a WORD, 4 for a DWORD).

For a string parameter, this property returns the number of characters in the string (string length).

Parameters:
psSize Receives the current size of the parameter.
Precondition:
psSize is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Type

IParameter::Min [out, retval] VARIANT *  pvtMin  ) 
 

Returns the minimum value of this parameter.

This property only contains a valid value if AdditionalInfoPresent is true and this is a ntUnsignedNumber parameter type (see Type), else it will returns the absolute minimum value of the value (which depends on the Size of the parameter).

Parameters:
pvtMin Receives the current minimum value of the parameter.
Precondition:
pvtMin is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
AdditionalInfoPresent, Max, Default, Value

IParameter::Max [out, retval] VARIANT *  pvtMax  ) 
 

Returns the maximum value of this parameter.

This property only contains a valid value if AdditionalInfoPresent is true and this is a ntUnsignedNumber parameter type (see Type), else it will returns the absolute maximum value of the value (which depends on the Size of the parameter).

Parameters:
pvtMax Receives the current maximum value of the parameter.
Precondition:
pvtMax is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
AdditionalInfoPresent, Min, Default, Value

IParameter::Default [out, retval] VARIANT *  pvtDefault  ) 
 

Returns the default factory setting of this parameter.

This property only contains a valid value if AdditionalInfoPresent is true and this is a ntUnsignedNumber parameter type (see Type), else it will returns the current value of this parameter.

Parameters:
pvtDefault Receives the default value for this parameter.
Precondition:
pvtDefault is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
AdditionalInfoPresent, Min, Max, Value

IParameter::IsReadOnly [out, retval] VARIANT_BOOL *  pfIsReadOnly  ) 
 

Returns true if this parameter is a read-only parameter.

If a parameter is read-only, the Save method can not be called for this parameter.

Parameters:
pfIsReadOnly Will be set to true if this parameter is read-only.
Precondition:
pfIsReadOnly is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Save

IParameter::IsPassword [out, retval] VARIANT_BOOL *  pfIsPassword  ) 
 

Returns true if this parameter is a password parameter.

If this parameter contains a password, the Value should not be shown in any UI since showing it will compromize security. If this is a password, display stars ("****") or something similar instead of the real value.

Parameters:
pfIsPassword Will be set to true if this parameter contains a password value.
Precondition:
pfIsPassword is not NULL.
Note:
This is a read-only property when used in scripting languages.

IParameter::IsModified [out, retval] VARIANT_BOOL *  pfIsModified  ) 
 

Returns true if the value of this parameter is modified.

If a parameter value has not been modified, Save has no effect.

Parameters:
pfIsModified Will be set to true if this parameter has been modified.
Precondition:
pfIsModified is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Save

IParameter::CanBeChangedByUser [out, retval] VARIANT_BOOL *  pfFlag  ) 
 

Returns true if this parameter is accessable at user level.

The current user level can be determined by passing "ReaderLevel" to the IProximityReader::GetProperty method.

Parameters:
pfFlag Will be set to true if this parameter is accessable at user level.
Precondition:
pfFlag is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
CanBeChangedByInstaller

IParameter::CanBeChangedByInstaller [out, retval] VARIANT_BOOL *  pfFlag  ) 
 

Returns true if this parameter is accessable at installer level.

The current user level can be determined by passing "ReaderLevel" to the IProximityReader::GetProperty method.

Parameters:
pfFlag Will be set to true if this parameter is accessable at installer level.
Precondition:
pfFlag is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
CanBeChangedByUser

IParameter::IsResetRequired [out, retval] VARIANT_BOOL *  pfIsResetRequired  ) 
 

Returns true if this parameter requires a restart to be effective after it has been changed.

When this property is true, and this parameter is changed, the IProximityReader::Reset method should be called after saving this parameter (or after saving a number of parameters at once) to activate the changes.

Parameters:
pfIsResetRequired Will be set to true if this parameter requires a reset.
Precondition:
pfIsResetRequired is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
IProximityReader::Reset

IParameter::AdditionalInfoPresent [out, retval] VARIANT_BOOL *  pfAdditionalInfoPresent  ) 
 

Returns true if this parameter contains additional information (min/max and default information).

If this property returns true, the Min, Max and Default value contain valid data.

Parameters:
pfAdditionalInfoPresent Will be set to true if this parameter includes additional information.
Precondition:
pfAdditionalInfoPresent is not NULL.
Note:
This is a read-only property when used in scripting languages.
See also:
Min, Max, Default, Value

IParameter::Save [in, defaultvalue(0xffff)] VARIANT_BOOL  fDisableRFID,
[out, retval] VARIANT_BOOL *  pfSucceeded
 

Save the new parameter settings into the reader.

Some parameters will require a reset after they have been changed to activate the changes. If this parameter's property IsResetRequired is set, a reset should be executed to apply the changes (use IProximityReader::Reset).

The value will not be saved when this is a read-only parameter (check the IsReadOnly property). The value will also not be saved if it has not been changed (check the IsModified property).

If a user or installer is capable to change a parameter, depends on the reader configuration, user levels etc. Check the CanBeChangedByUser and CanBeChangedByInstaller properties to see if modification is possible at certain user levels.

When saving a lot of parameters after each other, it is faster to disable the RFID interface before saving the first parameter, and re-enable it after the last user has been saved (and setting the fDisableRFID flag to false in this method). See IProximityReader::EnableRFID. The same applies to the reset, check each parameter if the reader should be reset to activate the parameter changes. If one or more parameters require a reset, it can be faster to perform the reset only once after changing all parameters.

When saving a parameter, the IParameterDatabase will fire an OnProcessInfo event, with processtype ptParameterdatabaseChange and sub process type sptItemModified. The changed parameter will be passed to the OnProcessInfo event in the Info parameter.

Parameters:
fDisableRFID When set to true (default), the RFID interface will be disabled while saving this parameter and re-enabled after the saving process has finished. This ensures that a user presenting a card cannot interfere with the save process.
pfSucceeded Set to true upon a successful save.
Precondition:
pfSucceeded is not NULL.
See also:
Value, IsResetRequired, CanBeChangedByUser, CanBeChangedByInstaller, IsModified, IsResetRequired.

IParameter::Refresh  ) 
 

Refresh this parameters value.

Refresh the value of this parameter by requesting the latest value from the reader.

See also:
Value.


© Copyright 2001 - 2006 Cross Point. Generated on Mon Mar 12 16:29:51 2007 Cross Point