Insert Method

Method: Cache::Insert

Summary:

Insert() copies cbData bytes from the buffer pointed to by pbData into a cache entry within the cache.

Syntax:

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

int Insert (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.

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:

The Insert() method inserts a key and an associated value into the cache. If the cache is full, a replacement is performed; the type of replacement is dependent on the cache replacement policy.

Example

char szVal  [26 + 1];

strcpy (szVal, "ABCDEFGHIJKLMNOPQRSTUVWXYZ");

// (note: in this case, the trailing NULL is inserted)

int iResult = pCache->Insert ((const QBYTE *)"Alphabet", // key
                              (QBYTE *) szVal,           // pbData (the value)
                              strlen(szVal)+1,           // cbData
                              0);                        // TTL

if (iResult != E_SUCCESS)
{
    // error handling here
}