IDictionary::get_Value, put_Value
.gif "Ee797268.c++_off(en-US,CS.10).gif")
.gif "Ee797268.vb_on(en-US,CS.10).gif")
The Value property allows you to get or set a name/value pair in the Dictionary.
Definition
Get method:
HRESULT IDictionary::get_Value(BSTRbstrName,VARIANT*Value);
Put method:
HRESULT IDictionary::put_Value(BSTRbstrName,VARIANTValue);
Putref method:
HRESULT IDictionary::putref_Value(BSTRbstrName,VARIANTValue);
Parameters
bstrName
[in] A BSTR that contains the name of the Dictionary key for which to retrieve a value or put a value.
Value
[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 Values
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.
Error Values
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.
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.
For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.
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.