IDictionary::get_Value, put_Value Property
The Value property allows you to get or set a name/value pair in the Dictionary.
HRESULT IDictionary::get_Value(
BSTR bstrName,
VARIANT* Value
);
HRESULT IDictionary::put_Value(
BSTR bstrName,
VARIANT Value
);
HRESULT IDictionary::putref_Value(
BSTR bstrName,
VARIANT Value
);
Property Value(
bstrName As String
) As Variant
Parameters
bstrName
[C++][in] A BSTR that contains the name of the Dictionary key for which to retrieve a value or put a value.
[Visual Basic]
A String that contains the name of the Dictionary key for which to retrieve a value or put a value.
Value
[C++][in] When putting the property, a VARIANT that contains the value to which the element specified by the key bstrName should be initialized.[out, retval] When getting the property, a pointer to a VARIANT used to return the value of the key specified by the bstrName parameter.
Return Value
[C++] These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details. If successful, this method returns S_OK. Otherwise, it returns an HRESULT indicating failure, and the Value out-value parameter is set to NULL.
[Visual Basic] None.
Error Values
[C++] These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.
[Visual Basic] This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.
Remarks
When reading the Value property using the get_Value method, if the key being accessed in the dictionary does not exist, a VARIANT of type VT_NULL is returned. Therefore, to logically delete a key from the dictionary, you can set the value for the key to VT_NULL and then to a client of the dictionary. It is indistinguishable from a key/value pair that does not exist. The Value parameter contains valid data only if the property is accessed successfully.
When putting a value, use the putref method if you are setting an object reference; use the put method if you are setting a scalar value.
Example
' dDict is a Dictionary object.
' first_name is a Dictionary key.
' v_first_name is a Variant.
v_first_name = dDict.value("first_name")
v_first_name = dDict("first_name")
' use this form if the value contains an object reference:
Set oSubObject = dDict("myObjectKey")
' Property syntax
' Note: There is a slight performance penalty for using
' these forms because a special implementation of IDispatch is used.
v_first_name = dDict.first_name
' If the key begins with an underscore then use braces around the key name.
v_first_name = dDict.[_first_name]