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

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