setItem method

Article
05/02/2017

Sets a key/value pair.

Syntax

HRESULT retVal = object.setItem(bstrKey, bstrValue);

Parameters

bstrKey [in]
Type: BSTR

The name of the key (a valid UTF-16 string, including the empty string).
bstrValue [in]
Type: BSTR

The 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.

Partager via