InsertCallerBuffer Method

Method: Cache::InsertCallerBuffer

Summary:

InsertCallerBuffer() copies cbData bytes from the buffer pointed to by pbData into a cache entry within the cache. The cache does not allocate new memory for the data - it uses the buffer that the caller has allocated.

Syntax:

int InsertCallerBuffer (const QBYTE *szKey, 
                        const QBYTE *pbData,
                        const size_t cbData,
                        const unsigned int numSecondsTTL);

int InsertCallerBuffer (const QWORD *wszKey, 
                        const QBYTE *pbData,
                        const size_t cbData,
                        const unsigned int numSecondsTTL);

Parameters:

1) szKey or wszKey: the key

2) pbData: a pointer to a buffer of bytes that will be inserted into the cache. This
   buffer will have been allocated by the caller; the cache will free the memory pointed
   to by the buffer pointer.

3) cbData: a count of bytes of the data. This value does not necessarily need to include
   space for a trailing NULL. Exactly cbData bytes of the buffer pointed to by pbData
   will be stored in the cache.

4) numSecondsTTL: number of seconds for the "time-to-live" value.

Return values:

  E_KEY_INVALIDKEYTYPE
  E_INVALID_KEYVALUE
  E_CACHE_DUPLICATE_KEY_FOUND_ENTRY_NOT_REPLACED
  E_SUCCESS

Remarks:

InsertCallerBuffer() is similar to the Insert() method. It differs as follows: InsertCallerBuffer() uses the caller-allocated buffer pointed to by pbData. The caller allocates a buffer of data, and passes a pointer in pbData. The cache will free the memory pointed to by pbData, during one of the following:

1) another Insert operation with duplicate key (where allowed), or Replace operation
2) a cache-directed replacement, during which a cache entry eviction takes place
3) during cleanup of the cache

Example

// the caller buffer:

QBYTE *pbBuffer = (QBYTE *) malloc (26 + 1);

strcpy ((char *) pbBuffer, "ABCDEFGHIJKLMNOPQRSTUVWXYZ");

int iResult = pCache->InsertCallerBuffer ((const QBYTE *) "Alphabet", // key
                                          pbBuffer, 
                                          strlen ((char *) pbBuffer) + 1, // cbData
                                          300);  // TTL
if (iResult != E_SUCCESS)
{
    // error handling here
}