Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 1 - Introduction to QuickDraw 3D / QuickDraw 3D Reference

QuickDraw 3D Routines / Managing Strings

Q3CString_GetString

You can use the Q3CString_GetString function to get the character data of a C string object.

TQ3Status Q3CString_GetString (
TQ3StringObject stringObj, 
char **string);

stringObj

A C string object.

string

On entry, the value NULL. On exit, a pointer to a copy of the character data associated with the specified C string object.

DESCRIPTION

The Q3CString_GetString function returns, through the string parameter, a pointer to a copy of the character data associated with the C string object specified by the stringObj parameter. The value of the string parameter must be NULL when you call Q3CString_GetString, because it allocates memory and overwrites the string parameter. For instance, the following sequence of calls will cause a memory leak:

myStatus = Q3CString_GetString(myStringObj, &myString);
myStatus = Q3CString_GetString(myStringObj, &myString);

After the second call to Q3CString_GetString, the memory allocated by the first call to Q3CString_GetString is leaked; you cannot deallocate that memory because you've lost its address. You must make certain to call Q3CString_EmptyData to release the memory allocated by Q3CString_GetString when you are finished using the string data, and always before calling Q3CString_GetString with the same string pointer. Here is an example:

myStatus = Q3CString_GetString(myStringObj, &myString);
myStatus = Q3CString_EmptyData(&myString);
myStatus = Q3CString_GetString(myStringObj, &myString);

If the value of the string parameter is not NULL, Q3CString_GetString generates a warning.

You should use Q3CString_GetString only with string objects of type kQ3StringTypeCString.

ERRORS AND WARNINGS

kQ3WarningPossibleMemoryLeak