CString::LockBuffer

  • Article

This method locks a string in the buffer.

LPTSTR LockBuffer( );

Return Value

Returns a pointer to a CString object or a NULL-terminated string.

Remarks

By calling LockBuffer, you create a copy of the string, and then set the reference count to –1. When the reference count is set to –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 exclusive hold of the string on the buffer remains intact.

After you have finished with LockBuffer, call UnlockBuffer to reset the reference count to 1.

If you call GetBuffer on a locked buffer, and you set the GetBuffer parameter nMinBufLength to greater than the length of the current buffer, you 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.

Requirements

  Windows CE versions: 1.0 and later
  Header file: Declared in Afx.h
  Platform: H/PC Pro, Palm-size PC, Pocket PC

See Also

CString::UnlockBuffer, CString::GetBuffer, CString::ReleaseBuffer