setItem method
Sets a key/value pair.
.png){kind=icon} .png){kind=icon} |
Syntax
HRESULT retVal = object.setItem(bstrKey, bstrValue);
Parameters
bstrKey [in]
Type: BSTRThe name of the key (a valid UTF-16 string, including the empty string).
bstrValue [in]
Type: BSTRThe value (a valid UTF-16 string) of the key/value pair.
Return value
Type: HRESULT
This method can return one of these values.
| Return code | Description |
|---|---|
| S_OK | The operation completed successfully. |
| E_OUTOFMEMORY | There is insufficient memory to complete the operation. |
| E_ACCESSDENIED | The operation is not allowed. |
| E_INVALIDARG | One or more arguments are invalid. |
| W3CException_DOM_QUOTA_EXCEEDED_ERR | IE9 mode only. The operation would exceed storage limits. |
Exceptions
| Exception | Condition |
|---|---|
| QuotaExceededError | The operation would exceed storage limits. For versions earlier than Internet Explorer 10, QUOTA_EXCEEDED_ERR is returned. |
Standards information
- Web Storage, Section 4.1
Remarks
This implementation of IHTMLStorage::setItem differs from IHTMLStorage::setItem in return code only. In IE9 mode, this method might also return W3CException_DOM_QUOTA_EXCEEDED_ERR.
Any valid UTF-16 string, including the empty string, is a valid key name. If bstrKey or bstrValue are not valid UTF-16 strings, the IHTMLStorage::setItem method returns E_INVALIDARG
This method first checks if a key/value pair with the specified bstrKey already exists in the list associated with the object. If not, a new key/value pair with the given value is added to the list. If the key/value pair already exists, the value is updated.
If the size of the value is larger than the disk quota remaining for the storage area, E_OUTOFMEMORY is returned. If necessary, check IHTMLStorage::remainingSpace before storing the value.
Attempts to read or write a secured item from script running in the context of an unsecured URL are not permitted.
See also
Reference