RetrieveDataLength Method

Method: Cache::RetrieveDataLength

Summary:

RetrieveDataLength() retrieves the length in bytes of a cache entry's Document field's data.

Syntax:

int RetrieveDataLength (const QBYTE *szKey,
                        size_t *pcbData);

int RetrieveDataLength (const QWORD *wszKey,
                        size_t *pcbData);

Parameters:

1) szKey or wszKey: the key

2) pcbData: pointer to a variable that on return will contain the exact number of bytes of the data that is stored in the cache entry.

Return values:

  E_KEY_INVALIDKEYTYPE
  E_INVALID_KEYVALUE
  E_KEY_NOTFOUND
  E_CACHE_RETRIEVE_ENTRY_MARKED_FOR_DELETION
  E_CACHE_RETRIEVE_ENTRY_IS_EXPIRED
  E_SUCCESS

Remarks:

If the original data that was inserted into the cache had contained a null terminator
byte, the count returned in *pcbData will include space for this trailing byte.

RetrieveDataLength() includes internal synchronization; it performs a directory lookup followed by a retrieval of the data length field from the cache entry's Document member field.

If the key is not found (E_KEY_NOTFOUND), RetrieveDataLength() will increment
the global miss count. However, if the key is found and the function is successful,
the global hit count is not incremented, since a successful call to RetrieveDataLength()
is normally followed by a call to Retrieve().

RetrieveDataLength() does not modify Replacement metadata (e.g. LRU, LFU).

Example

size_t cbData = 0;

int iResult = pCache->RetrieveDataLength ((const QBYTE *) "AAA", // key
                                          &cbData);
if (iResult != E_SUCCESS)
{
    // error handling here
}