CSimpleStringT::LockBuffer
Disables reference counting and protects the string in the buffer.
PXSTR LockBuffer( );
Return Value
A pointer to a CSimpleStringT object or a null-terminated string.
Remarks
Call this method to lock the buffer of the CSimpleStringT object. By calling LockBuffer, you create a copy of the string, with a –1 for the reference count. When the reference count value is -1, the string in the buffer is considered to be in a "locked" state. While in a locked state, the string is protected in two ways:
No other string can get a reference to the data in the locked string, even if that string is assigned to the locked string.
The locked string will never reference another string, even if that other string is copied to the locked string.
By locking the string in the buffer, you ensure that the string's exclusive hold on the buffer will remain intact.
After you have finished with LockBuffer, call UnlockBuffer to reset the reference count to 1.
Note
If you call GetBuffer on a locked buffer and you set the GetBuffer parameter nMinBufferLength to greater than the length of the current buffer, you will lose the buffer lock. Such a call to GetBuffer destroys the current buffer, replaces it with a buffer of the requested size, and resets the reference count to zero.
For more information about reference counting, see the following articles:
Managing Object Lifetimes through Reference Counting in the Windows SDK
Implementing Reference Counting in the Windows SDK
Rules for Managing Reference Counts in the Windows SDK
Example
The following example demonstrates the use of CSimpleStringT::LockBuffer.
CSimpleString str(_T("Hello"), pMgr);
TCHAR ch;
str.LockBuffer();
ch = str.GetAt(2);
_tprintf_s(_T("%c"), ch);
str.UnlockBuffer();
Requirements
Header: atlsimpstr.h