LayerCOS_Layer
ObjectCosStream

A stream is a sequence of characters that can be read a portion at a time. Streams are used for objects with large amounts of data, such as images, page content, or private data a plug-in creates. A stream consists of these elements, which are listed in their relative order in the stream object, starting at the beginning. See Section 3.2.7 in the PDF Reference for a description of the stream object.



Define Summary
 Define
 CosNewStream64
 CosStreamLength64
 CosStreamPos64
Typedef Summary
 Typedef
 CosStreamStartAndCode
Enumeration Summary
 Enumeration
  CosStreamOpenMode
Constants that specify whether filters and decryption should be applied to the stream's data.
Method Summary
 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.
 
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


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:

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.

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:

 
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

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

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.

See Also

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.

See Also

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

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

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

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

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