RetrieveNoCopy Method

Method: Cache::RetrieveNoCopy

Summary:

RetrieveNoCopy() gets a pointer to the data of a cache entry.

Syntax:

int RetrieveNoCopy (const QBYTE *szKey, 
                    QBYTE **ppbData);

int RetrieveNoCopy (const QWORD *wszKey, 
                    QBYTE **ppbData);

Parameters:

1) szKey or wszKey: the key

2) ppbData: pointer to a pointer that on return will point to a buffer containing the data. This buffer is maintained by the cache and must not be deleted or free'd.

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:

RetrieveNoCopy() does a cache retrieve operation, which affects replacement metadata, however it does not copy any data; it simply returns a pointer to the cache entry data, in ppbData.

When used in multi-threaded situations, this is unreliable unless the caller first calls SetCacheEntryDoNotEvictFlag () to mark the cache entry so that it will not be evicted. Otherwise, the Retrieve() method should be used, since it copies the data to a buffer that is provided by the caller.

Example

// First, get the length in bytes of the data:

size_t cbData = 0;

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

QBYTE *pbData = NULL;

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