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 this format:

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

stream

... data, possibly encoded...

endstream

See the description of the Stream Objects in "Objects," in ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 7.3.8, page 19. You can find this document on the web store of the International Standards Organization (ISO).

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 description of the DecodeParms attribute in Table 5 in ISO 32000-1:2008, Document Management-Portable Document Format- Part 1: PDF 1.7, section 7.3.8.2, page 20. You can find this document on the web store of the International Standards Organization (ISO).

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.

For attributeDict, see the description of Stream Objects in the ISO 32000-1:2008, Document Management-Portable Document Format-Part 1: PDF 1.7, section 9.9, page 288. You can find this document on the web store of the International Standards Organization (ISO).

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.

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.

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.

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.