Returns a newly allocated buffer containing a copy of the Cos object's string value. Upon return, nBytes contains the number of bytes in the original Cos string. CosCopyStringValue() never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling ASfree().
CosCopyStringValue() allocates extra memory past the end of the string and writes zeros into these extra bytes to ensure that the string is NULL-terminated whether viewed as a UTF-16 (Unicode) string or as a C string (these bytes are not included in the number returned in nBytes). If the Cos string has 0 length, nBytes will be 0, and a pointer to newly allocated memory containing some zero bytes is returned (that is, CosCopyStringValue() still returns a NULL-terminated string but with zero length).
An out-of-memory exception is raised if insufficient memory is available. It can also raise any exception that CosStringValue() can raise.
Note: In general, the returned value is not a NULL-terminated C string. Cos string objects are binary and can contain arbitrary byte sequences, including NULL characters. Standard C string handling functions may not work as expected.
char *CosCopyStringValue(CosObj obj, ASTCount *nBytes); obj | IN The Cos object whose string value is copied and returned.
|
nBytes |
CosObj CosNewString(CosDoc dP, ASBool indirect, const char *str, ASTArraySize nBytes); dP | The document in which the string is used.
|
indirect | If
true, it creates the string as an indirect object, and sets the document ( dP) object's PDDocNeedsSave flag (see PDDocFlags). If false, it creates the string as a direct object. |
str | The value that the new string will have. It is not a C string, since Cos strings can contain
NULL characters. The data in str is copied; that is, if str was dynamically allocated, it can be freed after this call. |
nBytes | The length of
str. |
ASBool CosStringGetHexFlag(CosObj cosObj); cosObj | IN/OUT The
CosString for which the hex flag is obtained. |
ASBool CosStringSetHexFlag(CosObj cosObj, ASBool setHex); cosObj | The
CosString for which the hex flag is set. |
setHex | The value to set for the flag.
|
setHex. Gets the value of a string Cos object, and the string's length.
An exception is raised if the type of obj is not a CosString.
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 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.
char *CosStringValue(CosObj obj, ASTCount *nBytes); obj | IN The object whose value is obtained.
|
nBytes |
obj.
Copies at most bufferSize bytes from the obj parameter's string value into buffer, and stores the actual length of the Cos string in *nBytes. If bufferSize is greater than the length of the Cos string, the remaining bytes in buffer have undefined values upon return.
A bad-parameter exception is raised if bufferSize is less than 0 or nBytes is NULL. It can also raise any exception that CosStringValue() can raise.
Note: In general, the returned value is not a NULL-terminated C string. Cos string objects are binary data and can contain any arbitrary byte sequence, including embedded NULL characters. Standard C string handling functions may not work as expected.
char *CosStringValueSafe(CosObj obj, char *buffer, ASTArraySize bufferSize, ASTCount *nBytes); obj | The Cos object whose string value is copied.
|
buffer | The buffer into which the Cos string value is copied, or
NULL. |
bufferSize | The length of
buffer or 0. |
nBytes | (Filled by the method) The length of the original Cos string in bytes (which may be more than
bufferSize). It must be a non- NULL pointer. |
NULL.