CosStringValue Missing Notes

by Mark Gavin
I happened to be looking through the current documentation for the Adobe Acrobat SDK on the Adobe site and ran across something that looked odd. The documentation for CosStringValue has been dramatically abridged to remove all of the notes explaining what you need to know when using CosStringValue.
char* CosStringValue(CosObj obj, ASTCount* nBytes)
CosStringValue can produce odd intermittent results if used incorrectly.
Following are the three key items you need to know when using CosStringValue:
  1. CosStringValue may not return a C-String.
  2. The data pointed to by the returned pointer may contain embedded null bytes.
  3. The memory location used by CosStringValue can be reused at any time.

More recent versions of the Adobe Acrobat SDK / Adobe PDF Library have additional calls which can be used instead of CosStringValue which are much safer to work with in general use:

char* CosCopyStringValue(CosObj obj, ASTCount* nBytes)
char* CosStringValueSafe(CosObj obj, char* buffer, ASTArraySize bufferSize, ASTCount* nBytes)
Following is a link to the Adobe Acrobat SDK / Adobe PDF Library documentation on the Adobe site
Following are the missing notes which can be found in older versions of the “Acrobat® and PDF Library API Reference”

Note: The pointer returned from this method is not guaranteed to remain valid if CosStringValue() is called again. It is recommended that you use CosStringValueSafe() or CosCopyStringValue() instead; these methods place the string into a user-allocated buffer.

Note: The caller must immediately copy the returned string. The memory pointed to be the return value may become invalid if any memory-allocating calls are made. In particular, consider the sequence:

str1 = CosStringValue(...);
str2 = CosStringValue(...);

In this case, the contents of str1 may be invalid by the time the second CosStringValue() call returns.

Note: The returned value is not a C-style string. Cos string objects can contain NULL bytes. Standard C string-handling functions may not work as expected.