setItem method

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.

See also

Reference

IHTMLStorage::getItem

IHTMLStorage::remainingSpace