COS_Layer.CosStream (Acrobat)

	Define
	CosNewStream64
	CosStreamLength64
	CosStreamPos64

	Typedef
	CosStreamStartAndCode

	Enumeration
	`CosStreamOpenMode` Constants that specify whether filters and decryption should be applied to the stream's data.

	Method
	CosObj CosNewStream(CosDoc dP, ASBool indirect, ASStm stm, CosStreamStartAndCode sourceStart, ASBool encodeTheSourceData, CosObj attributesDict, CosObj encodeParms, CosByteMax sourceLength) Creates a new Cos stream, using data from an existing ASStm. The data is copied, so the source stream may be closed after CosNewStream returns.
	CosObj CosNewStream64(CosDoc dP, ASBool indirect, ASStm stm, ASInt64 stmStartPos, ASBool stmDataIsDecoded, CosObj attributesDict, CosObj encodeParms, ASInt64 sourceLength, ASBool allowDelayedRead) Creates a new Cos stream, using data from an existing ASStm. For details, see CosNewStream() .
	CosObj CosStreamDict(CosObj stream) Gets a stream's attributes dictionary.
	ASTArraySize CosStreamLength(CosObj stream) Gets the length of a Cos stream from the Length key in the stream's attributes dictionary. This specifies the length of the undecoded data, which is the number of bytes in the stream before the Filter (if any) is applied.
	ASInt64 CosStreamLength64(CosObj stream) Gets the length of a Cos stream from the Length key in the stream's attributes dictionary. See CosStreamLength() for details. This is the same as CosStreamLength() , except that the return value is a 64-bit integer instead of a 32-bit integer.
	ASStm CosStreamOpenStm(CosObj stream, CosStreamOpenMode mode) Creates a new, non-seekable ASStm for reading data from a Cos stream. The data in the Cos stream may be filtered and encrypted. After opening the Cos stream, data can be read from it into memory using ASStmRead() . When reading is completed, close the stream using ASStmClose() .
	ASTCount CosStreamPos(CosObj stream) Gets the byte offset of the start of a Cos stream's data in the PDF file (which is the byte offset of the beginning of the line following the stream token). Use this method to obtain the file location of any private data in a stream that you need to read directly rather than letting it pass through the normal Cos mechanisms. For example, this could apply to a QuickTime video embedded in a PDF file.
	ASFilePos64 CosStreamPos64(CosObj stream) Gets the byte offset of the start of a Cos stream's data in the PDF file. For details, see CosStreamPos() . This is the same as CosStreamPos() , except that the return value is a 64-bit file position instead of a 32-bit file position.

Defines Detail

CosNewStream64

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosNewStream64 CosCallMacro(CosNewStream64, 7)

File: CosCalls.h

Line: 464

CosStreamLength64

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosStreamLength64 CosCallMacro(CosStreamLength64, 7)

File: CosCalls.h

Line: 465

CosStreamPos64

Product availability: Acrobat, Reader

Platform availability: Macintosh, Windows, UNIX

Syntax


#define CosStreamPos64 CosCallMacro(CosStreamPos64, 7)

File: CosCalls.h

Line: 466

Typedefs Detail

CosStreamStartAndCode

Product availability: All

Platform availability: All

Syntax

typedef ASInt32 CosStreamStartAndCode;

File: CosExpT.h

Line: 39

Enumeration Detail

CosStreamOpenMode

Product availability: All

Platform availability: All

Syntax

enum CosStreamOpenMode {

  cosOpenRaw,


 


  cosOpenUnfiltered,


 


  cosOpenFiltered,


 


  cosOpenRawIgnoreFKey,


 


  cosOpenUnfilteredIgnoreFKey,


 


  cosOpenFilteredIgnoreFKey

}

See Also

CosStreamOpenStm

File: CosExpT.h

Line: 134

Elements

	cosOpenRaw	The data will be decrypted but not filtered.

	cosOpenFiltered	The data will be both decrypted and filtered. (This is the usual case.)

Method Detail

CosNewStream

()

Product availability: All

Platform availability: All

Syntax





CosObj CosNewStream(CosDoc dP, ASBool indirect, ASStm stm, CosStreamStartAndCode sourceStart, ASBool encodeTheSourceData, CosObj attributesDict, CosObj encodeParms, CosByteMax sourceLength)

Creates a new Cos stream, using data from an existing ASStm. The data is copied, so the source stream may be closed after CosNewStream returns.

This method creates a Cos stream object by writing its PDF representation to an intermediate file, in the format specified in the PDF Reference:

<</Length ... /Filter ... /DecodeParms ...>>

stream

... data, possibly encoded ...

endstream

This occurs in four steps:

Step 1: Writing the attribute dictionary

If attributesDict is a valid Cos dictionary, the method writes that dictionary to the intermediate file. Otherwise, it creates a new direct dictionary, determining a Length key according to the sourceLength value:

If sourceLength is negative, or if the source data is to be encoded (see below), the value of the Length key is a reference to a new indirect object, whose value will be set in Step 4.
Otherwise, Length is a direct scalar representing sourceLength.

The dictionary that is written becomes the new stream's attribute dictionary.

Step 2: Reading the data

sourceStart determines where in the source stream to begin reading, and whether the source is seekable.

If sourceStart is a negative number, the source is assumed to be non-seekable but positioned at the point where reading should start.
Otherwise, the source is assumed to be seekable, and reading starts at the position indicated by sourceStart. If sourceStart is zero, data is read from the beginning of the source stream. Positive values for sourceStart may be used, for instance, to skip over initial data in the stream.

Step 3: Encoding the data

If attributesDict is a valid Cos dictionary, it contains a Filter key, and encodeTheSourceData is true, the method encodes the data after reading it from the source stream and before writing it to the intermediate file.

The attributesDict is used as the new stream's dictionary. The Filter entry in this dictionary indicates how the data in the resulting Cos stream object will be subsequently decoded; the value may be the name of a decoding filter or an array of such names. Specify multiple filters in the order they should be applied to decode the data (if parameters are needed to decode the data, they are specified as the value of the DecodeParms key in attributesDict. See the PDF Reference for details). For each decoding filter, there is a corresponding encoding filter, which the method applies to the source data during this step.

If parameters are needed to encode the data, they must be specified in the call by encodeParms (the encoding parameters are often different from the decoding parameters). The encodeParms parameter is optional for all encoding filters except DCTDecode and JBIG2Decode. See the encodeParms field of PDEFilterSpec.

If an array of filters is supplied, and at least one of them requires encoding parameters, then a corresponding array of encoding parameters is also required. Use the NULL object to represent default parameters for filters that have defaults.

In any other case, the method copies the source data directly into the Cos stream with no encoding. If sourceLength is negative, it reads bytes until the source reaches its EOF. Otherwise, sourceLength indicates how many bytes to read from the source, and an exception is raised if the source reaches EOF before that.

Step 4: Writing the data

After the data is written, if the value of the Length key in the attributes dictionary was an indirect reference (either because it was supplied that way in attributesDict, or because it was created that way in Step 1, the value of that indirect object is set to the number of bytes actually written (that is, the encoded length if the data was encoded). An indirect Length key is useful for one-pass writing, when the size of the written data is not known in advance, either because the data was to be encoded, or because there was no way to know how much data there would be before the source reached its EOF.

An exception is raised if attributesDict is neither the NULL object nor a direct Cos dictionary, sourceStart is nonnegative but the source is not seekable, or if sourceLength is nonnegative but the source stream reaches EOF before that many bytes have been read.

Parameters

	`dP` —	The Cos document in which the newly created stream will be used.

	`indirect` —	Must always be `true`, specifying that the Cos stream is created as an indirect object (all streams are indirect). This also sets the document's `PDDocNeedsSave` flag (see `PDDocFlags`).

	`stm` —	The source stream containing the data to copy into the new stream. The caller is responsible for closing `stm` after `CosNewStream()` returns. The source stream can be any readable `ASStm`. Typical sources are: Files (`ASFileStmRdOpen()`) or memory (`ASMemStmRdOpen()`). These streams are always seekable. Arbitrary procedures (`ASProcStmRdOpen()` or `ASProcStmRdOpenEx()`), or other Cos streams (`CosStreamOpenStm()`). These streams are always non-seekable.

	`sourceStart` —	The byte offset into `stm` from which data reading starts for a seekable stream. If the value is negative, it specifies that the stream is not seekable.

	`encodeTheSourceData` —	Determines whether the data in `stm` should be encoded using filters specified in `attributesDict` before it is written to the Cos stream. See the description of the encoding step above. If `attributesDict` is a `NULL` object or if the dictionary has no `Filter` key, this value is ignored.

	`attributesDict` —	Either the `NULL` Cos object, or a direct Cos dictionary containing stream attributes, such as the length of the Cos stream data and a list of decoding filters and parameters to apply to the data, as defined in Section 3.2.7 in the PDF Reference. See the encoding step in the description above.

	`encodeParms` —	The parameters to be used by the filters if the source data is encoded before it is written to the file. The parameters follow the structure for the value of the `DecodeParms` stream attribute described in Table 3.4 in the PDF Reference. See the encoding step in the description above. If no encoding parameters are needed, this value is ignored.

	`sourceLength` —	The amount of data to be read from the source. If negative (typically `-1`), data is read from the source until it reaches its EOF. See Step 1 in the description above.

Returns

The newly created stream Cos object.

See Also

CosObjDestroy
CosNewStream64

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 450

CosNewStream64

()

Product availability: All

Platform availability: All

Syntax





CosObj CosNewStream64(CosDoc dP, ASBool indirect, ASStm stm, ASInt64 stmStartPos, ASBool stmDataIsDecoded, CosObj attributesDict, CosObj encodeParms, ASInt64 sourceLength, ASBool allowDelayedRead)

Creates a new Cos stream, using data from an existing ASStm. For details, see CosNewStream().

This is the same as CosNewStream(), except that decodeLength is a 64-bit value instead of a 32-bit value, and allowDelayedRead enables the implementation to avoid making an intermediate copy of the stream data. This is useful when creating very large streams of data.

Parameters

	`dP` —	The Cos document in which the newly created stream will be used.

	`indirect` —	Must always be `true`, specifying that the Cos stream is created as an indirect object.

	`stm` —	The source stream containing the data to copy into the new stream.

	`stmStartPos` —	Starting position for the stream. Its default is `0`.

	`stmDataIsDecoded` —	A boolean value indicating whether the data in `stm` should be encoded using filters specified in `attributesDict`.

	`attributesDict` —	Either the `NULL` Cos object, or a direct Cos dictionary containing stream attributes.

	`encodeParms` —	The parameters to be used by the filters if the source data is to be encoded.

	`sourceLength` —	The amount of data to be read from the source.

	`allowDelayedRead` —	If this is `true` and `stm` permits seek operations, then the data from `stm` will not be read during this call, but rather at a subsequent time, and it may be read more than once. Important: In this case, the caller must not close `stm` until it is established, through some independent mechanism, that the data will not be read again (see `ASProcStmRdOpenEx()` for further details on this feature). If `allowDelayedRead` is `false`, the source data is copied during this call, so the source stream may be closed after `CosNewStream64()` returns.

Returns

The newly created stream Cos object.

See Also

CosNewStream
ASProcStmRdOpenEx

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2280

CosStreamDict

()

Product availability: All

Platform availability: All

Syntax





CosObj CosStreamDict(CosObj stream)

Gets a stream's attributes dictionary.

Parameters

stream —

IN/OUT The stream whose attributes dictionary is obtained.

Returns

The stream's attributes dictionary Cos object.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 885

CosStreamLength

()

Product availability: All

Platform availability: All

Syntax





ASTArraySize CosStreamLength(CosObj stream)

Gets the length of a Cos stream from the Length key in the stream's attributes dictionary. This specifies the length of the undecoded data, which is the number of bytes in the stream before the Filter (if any) is applied.

This has the same effect as calling CosIntegerValue(CosDictGetKeyString(stream, "Length")).

An exception is raised if the Length key is not found in the attributes dictionary, if its value is not an integer, or if its value is outside the range of 32-bit integers.

Parameters

stream —

The stream whose length is obtained.

Returns

The length of the stream.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 872

CosStreamLength64

()

Product availability: All

Platform availability: All

Syntax





ASInt64 CosStreamLength64(CosObj stream)

Gets the length of a Cos stream from the Length key in the stream's attributes dictionary. See CosStreamLength() for details. This is the same as CosStreamLength(), except that the return value is a 64-bit integer instead of a 32-bit integer.

This has the same effect as calling CosInteger64Value(CosDictGetKeyString(stream, "Length"))

An exception is raised if the Length key is not found in the attributes dictionary, or if its value is not an integer.

Parameters

stream —

The stream whose length is obtained.

Returns

The length of the stream.

See Also

CosStreamDict
CosStreamLength

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2299

CosStreamOpenStm

()

Product availability: All

Platform availability: All

Syntax





ASStm CosStreamOpenStm(CosObj stream, CosStreamOpenMode mode)

Creates a new, non-seekable ASStm for reading data from a Cos stream. The data in the Cos stream may be filtered and encrypted. After opening the Cos stream, data can be read from it into memory using ASStmRead(). When reading is completed, close the stream using ASStmClose().

Parameters

	`stream` —	The Cos stream object for which an `ASStm` is opened.

	`mode` —	This must be one of the `CosStreamOpenMode` values.

Returns

The newly-opened ASStm.

See Also

ASStmRead
ASStmWrite
CosNewStream

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 902

CosStreamPos

()

Product availability: All

Platform availability: All

Syntax





ASTCount CosStreamPos(CosObj stream)

Gets the byte offset of the start of a Cos stream's data in the PDF file (which is the byte offset of the beginning of the line following the stream token). Use this method to obtain the file location of any private data in a stream that you need to read directly rather than letting it pass through the normal Cos mechanisms. For example, this could apply to a QuickTime video embedded in a PDF file.

CosStreamPos() is only valid when called on a stream that is already stored in a PDF document. If the stream was created using CosNewStream(), the new stream is stored in the document's temp file, and you cannot invoke CosStreamPos() on it. After the file has been saved, you can use CosStreamPos() on the stream.

Parameters

stream —

The stream whose current position is obtained.

Returns

The byte offset of the start of the Cos stream's data in the PDF file.

See Also

CosStreamDict
CosStreamLength

Exceptions

cosErrInvalidObj is raised if the stream object has not yet been saved to the PDF file. In other words, before you can call


CosStreamPos()

on a newly created stream, you must first save the PDF file.

Since

PI_COS_VERSION >= 0x00020000

File: CosProcs.h

Line: 929

CosStreamPos64

()

Product availability: All

Platform availability: All

Syntax





ASFilePos64 CosStreamPos64(CosObj stream)

Gets the byte offset of the start of a Cos stream's data in the PDF file. For details, see CosStreamPos(). This is the same as CosStreamPos(), except that the return value is a 64-bit file position instead of a 32-bit file position.

Parameters

stream —

The stream whose current position is obtained.

Returns

The byte offset of the start of the Cos stream's data in the PDF file.

See Also

CosStreamPos
CosStreamLength

Exceptions

cosErrInvalidObj is raised if the stream object has not yet been saved to the PDF file.

Since

PI_COS_VERSION >= 0x00070000

File: CosProcs.h

Line: 2315

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
CosStream	Defines \| Typedefs \| Enumerations \| Methods

	cosOpenRaw,

	cosOpenUnfiltered,

	cosOpenFiltered,

	cosOpenRawIgnoreFKey,

	cosOpenUnfilteredIgnoreFKey,

	cosOpenFilteredIgnoreFKey

Layer	COS_Layer
Object	CosStream