LayerCOS_Layer
ObjectCosString

A string is a sequences of characters, enclosed in parentheses. See Section 3.2.3 in the PDF Reference for details.



Define Summary
 Define
 CosCopyNameStringValue
Method Summary
 Method
 
Returns a newly allocated buffer containing a copy of the Cos object's name as a NULL-terminated string. Upon return, nBytes contains the number of bytes in the string. CosCopyNameStringValue() never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling ASfree() .
 
char* CosCopyStringValue(CosObj obj, ASTCount* nBytes)
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() .
 
CosObj CosNewString(CosDoc dP, ASBool indirect, const char* str, ASTArraySize nBytes)
Creates and returns a new Cos string object.
 
Gets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.
 
ASBool CosStringSetHexFlag(CosObj cosObj, ASBool setHex)
Sets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.
 
char* CosStringValue(CosObj obj, ASTCount* nBytes)
Gets the value of a string Cos object, and the string's length.
 
char* CosStringValueSafe(CosObj obj, char* buffer, ASTArraySize bufferSize, ASTCount* nBytes)
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.
Defines Detail
CosCopyNameStringValue 
Product availability: Acrobat, Reader
Platform availability: Macintosh, Windows, UNIX

Syntax

#define CosCopyNameStringValue CosCallMacro(CosCopyNameStringValue,7)

File: CosCalls.h
Line: 454




Method Detail
CosCopyNameStringValue()
Product availability: All
Platform availability: All

Syntax

char* CosCopyNameStringValue(CosObj obj, ASTCount* nBytes)

Returns a newly allocated buffer containing a copy of the Cos object's name as a NULL-terminated string. Upon return, nBytes contains the number of bytes in the string. CosCopyNameStringValue() never returns NULL; it raises an exception if the allocation fails. The client is responsible for freeing the result by calling ASfree() .

Unlike Cos strings, the strings corresponding to Cos names are NULL-terminated.

This routine will avoid creating an ASAtom corresponding to the object's name and is generally more efficient than copying the value returned by ASAtomGetString(CosNameValue(obj)). (ASAtom objects consume global memory that is not deallocated.)

An out-of-memory exception is raised if insufficient memory is available.

Parameters

obj — 

IN A Cos name object.

 
nBytes — 

OUT The length of the name of the Cos object, and therefore the length of the returned string. nBytes may be NULL if you do not care how many bytes are in the name.

Returns

A copy of the Cos object's name, as a NULL-terminated string.

See Also

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h
Line: 2153
CosCopyStringValue() 
Product availability: All
Platform availability: All

Syntax

char* CosCopyStringValue(CosObj obj, ASTCount* nBytes)

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.

Parameters

obj — 

IN The Cos object whose string value is copied and returned.

 
nBytes — 

OUT (Filled by the method) The length of the original Cos string in bytes. It can be NULL if you do not care how many bytes were in the original string.

Returns

A copy of the Cos object's string value.

See Also

Since

PI_COS_VERSION >= 0x00050000

File: CosProcs.h
Line: 1426
CosNewString() 
Product availability: All
Platform availability: All

Syntax

CosObj CosNewString(CosDoc dP, ASBool indirect, const char* str, ASTArraySize nBytes)

Creates and returns a new Cos string object.

Parameters

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.

Returns

The newly created string Cos object.

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 237
CosStringGetHexFlag() 
Product availability: All
Platform availability: All

Syntax

ASBool CosStringGetHexFlag(CosObj cosObj)

Gets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.

Parameters

cosObj — 

IN/OUT The CosString for which the hex flag is obtained.

Returns

The current value of the flag.

See Also

Exceptions

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h
Line: 1271
CosStringSetHexFlag() 
Product availability: All
Platform availability: All

Syntax

ASBool CosStringSetHexFlag(CosObj cosObj, ASBool setHex)

Sets the hex flag of the CosString. The hex flag specifies whether the CosString should be written out as hex when writing the Cos Object to file.

Parameters

cosObj — 

The CosString for which the hex flag is set.

 
setHex — 

The value to set for the flag.

Returns

The value of setHex.

See Also

Exceptions

Since

PI_COS_VERSION >= 0x00040000

File: CosProcs.h
Line: 1258
CosStringValue() 
Product availability: All
Platform availability: All

Syntax

char* CosStringValue(CosObj obj, ASTCount* nBytes)

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.

Parameters

obj — 

IN The object whose value is obtained.

 
nBytes — 

OUT (Filled by the method) The length of the string, in bytes. It must be a non-NULL pointer.

Returns

The value of obj.

See Also

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h
Line: 571
CosStringValueSafe() 
Product availability: All
Platform availability: All

Syntax

char* CosStringValueSafe(CosObj obj, char* buffer, ASTArraySize bufferSize, ASTCount* nBytes)

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.

Parameters

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.

Returns

A copy of the Cos string value or an exception. It will never return NULL.

See Also

Since

PI_COS_VERSION >= 0x00050000

File: CosProcs.h
Line: 1455