The Buffer class provides a memory buffer object that can be used to contain blocks of data read and written to devices. Buffer objects must always be created by the stub writer. If they are attached to the Kwd_List by way of the BUFFER_LIST keyword, then Buffer object destruction will occur automatically by DDTT.

When a test script writer references a buffer name in a test script such as in the DEV_ALIAS READ_SECTOR BUFFER1=ALPHA, ALPHA is only the specified name of the buffer, not the actual Buffer object. The function stub must create the actual Buffer object and associate the name, ALPHA, with the created Buffer object. The function stub uses the DDTT keyword, BUFFER1, to access the Buffer's specified name, ALPHA.

The following constructor method is available for Buffer objects:

   Buffer(const char * name, size_t size, void * = NULL);

The following methods are available for operating on Buffer objects:

   // Returns a pointer to the Buffer's data
   PVOID buffer();
   void reallocate(size_t size);
   int compare(Buffer&, size_t);
   PCHAR kwd();
   size_t size();

The following overridden operator methods are available for operating on Buffer objects:

   // Replace RHS Buffer with a copy of LHS Buffer
   Buffer& operator=(Buffer& buf2);
   // Compare Buffer objects
   BOOL operator==(Buffer&);

The #include "buffer.h" include statement must be at the top your C++ stub module in order to use Buffer objects. The following are some examples showing usage of the C++ methods provided to operate on Buffer objects.

   size_t size = 2048;
   Buffer * buf;
   .
   .
   buf = new Buffer( param["BUF_NAME"], size,
                 param.getPtr(BUFFER_LIST));

The above statement constructs a new Buffer object with memory block of length size bytes associated with the test script keyword BUF_NAME. The constructor also adds the new buffer to a BufferList attached to the Kwd_List, by the keyword BUFFER_LIST. By specifying the last parameter in the constructor, a BufferList pointer, DDTT, will automatically destroy the Buffer object when the current thread terminates. The BufferList parameter can be left out or specified as NULL, in which case, the new Buffer object is not attached to the Kwd_List. However, the user is then responsible for deleting the Buffer object when it is no longer required by the stub functions.

The delete buf; function destroys the Buffer object and deallocates its memory. For example:

   Buffer buf;
   void * ptr;
   .
   .
   ptr = buf.buffer();

The delete buf; function returns a pointer to the buffer's internal block of memory. For example:

   void * datap;
   .
   .
   datap = (param.getPtr(param["BUFFER"]))->buffer();

Buffer objects can be easily "dumped" to the standard DDTT log file as:

   Buffer buf1;
   .
   .
   param.files()->out1<<buf1;

The content of Buffer object buf1 is formatted in hexadecimal ASCII and is sent to the standard log file. This file returns a pointer to the Buffer object's memory block. The Buffer object is referenced by the keyword parameter BUFFER in the test script.

   size = 4096;
   buf.reallocate(size);

This function re-sizes the buffer to "size." The data in the old block is lost.

   Buffer buf, buf2;
   .
   .
   buf2 = buf;

The = operator is overridden to copy the block from one Buffer to another, re-sizing the destination Buffer if necessary.

   if( buf == buf2 )...

The == operator is overridden to return TRUE if two Buffers are identical; otherwise, the == operator is overridden to return FALSE.

   if( buf.compare(buf2, (size_t)1024) );

This function compares buf to buf2 for the specified number of bytes, or fewer bytes if one buffer is smaller than the specified number. It also returns the value from memcmp(). (0 if the buffers are equal, and so on.)

   size_t size2;
   .
   .
   size2 = buf.size();

This function returns the size of the buffer in bytes.

   Buffer * bufp;
   .
   .
   bufp = new Buffer("TEMP_BUF", (size_t)10000, NULL);
   .
   .
   bufp->Destroy();

This function deletes Buffer pointed to by bufp.


[Back: DdtOStream Class]
[Next: Adding New Grammar Specifications]