AS_Layer.ASStm (Acrobat)

	Typedef
	ASProcStmRdExHandler
	ASProcStmRdExHandlerRec
	ASStm
	ASStmRec A stream object definition (see ASStream.h). It is a data stream that may be a buffer in memory, a file, or an arbitrary user-written procedure. It is typically used to extract data from a PDF file. When writing or extracting data streams, the ASStm must be connected to a Cos stream.

	Structure
	_s_ASProcStmRdExHandler For use by ASProcStmRdOpenEx().

	Callback
	ASProcStmDestroyProc A callback for use by ASProcStmWrOpen() and ASProcStmRdOpenEx().
	ASProcStmGetLength A callback for use by ASProcStmRdOpenEx().
	ASProcStmSeekProc A callback for use by ASProcStmRdOpenEx().
	ASStmProc A callback for use by ASProcStmRdOpenEx() and ASProcStmWrOpen(). This should place data in the buffer specified by the parameter data.

	Method
	ASStm ASFileStmRdOpen(ASFile afile, ASSmallBufferSize bufSize) Creates a read-only ASStm from a file. The stream supports seek operations.
	ASStm ASFileStmWrOpen(ASFile afile, ASSmallBufferSize bufSize) Creates a writable ASStm from a file. The stream supports seek operations.
	ASStm ASMemStmRdOpen(const char* data, ASArraySize len) Creates a read-only ASStm from a memory-resident buffer. The stream supports seek operations.
	ASStm ASProcStmRdOpen(ASStmProc readProc, void* clientData) Creates a read-only ASStm from an arbitrary data-producing procedure. The stream does not support seek operations.
	ASStm ASProcStmRdOpenEx(ASProcStmRdExHandler handler, void* clientData) Extends ASProcStmRdOpen() and creates a read-only ASStm from an arbitrary data-producing procedure. The stream optionally supports seek operations, although external clients do not have the ability to initiate a seek operation.
	ASStm ASProcStmWrOpen(ASStmProc writeProc, ASProcStmDestroyProc destroyProc, void* clientData) Creates an ASStm from an arbitrary data-producing procedure. The stream does not support seek operations.
	void ASStmClose(ASStm stm) Closes the specified stream.
	ASTCount ASStmFlush(ASStm stm) Flushes any buffered data to the specified stream.
	ASTCount ASStmRead(char* ptr, ASTArraySize itemSize, ASTCount nItems, ASStm stm) Reads data from stm into memory.
	ASTCount ASStmWrite(const char* ptr, ASTArraySize itemSize, ASTCount nItems, ASStm stm) Writes data from a memory buffer into an ASStm.

Typedefs Detail

ASProcStmRdExHandler

Product availability: All

Platform availability: All

Syntax

typedef _s_ASProcStmRdExHandler ASProcStmRdExHandler;

File: ASExpT.h

Line: 556

ASProcStmRdExHandlerRec

Product availability: All

Platform availability: All

Syntax

typedef _s_ASProcStmRdExHandler ASProcStmRdExHandlerRec;

File: ASExpT.h

Line: 556

ASStm

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASStmRec* ASStm;

File: ASExpT.h

Line: 274

ASStmRec

Product availability: All

Platform availability: All

Syntax

typedef struct _t_ASStmRec ASStmRec;

A stream object definition (see ASStream.h). It is a data stream that may be a buffer in memory, a file, or an arbitrary user-written procedure. It is typically used to extract data from a PDF file. When writing or extracting data streams, the ASStm must be connected to a Cos stream.

File: ASExpT.h

Line: 274

Structure Detail

_s_ASProcStmRdExHandler

Product availability: All

Platform availability: All

Syntax

struct _s_ASProcStmRdExHandler {

  ASByteCount size;  


 


  ASStmProc readProc;  


 


  ASProcStmDestroyProc destroyProc;  


 


  ASProcStmSeekProc seekProc;  


 


  ASProcStmGetLength getLengthProc;  


 


  ASByteCount bufSize;  

}

For use by ASProcStmRdOpenEx().

File: ASExpT.h

Line: 540

Elements

	size	Set to `sizeof(ASProcStmRdExHandlerRec)`.

	bufSize	The size of the buffer to use for the stream. If this field is missing, the default is `65535`. If this field is present and has a value of `0`, then the default is implementation-specific.

Callbacks Detail

ASProcStmDestroyProc

Product availability: All

Platform availability: All

Syntax

void (*ASProcStmDestroyProc)(void *clientData)

A callback for use by ASProcStmWrOpen() and ASProcStmRdOpenEx().

This is called at the end of the stream so you can do clean up and free allocated memory.

File: ASExpT.h

Line: 504

ASProcStmGetLength

Product availability: All

Platform availability: All

Syntax

ASFilePos64 (*ASProcStmGetLength)(void *clientData)

A callback for use by ASProcStmRdOpenEx().

This is called to get the length of the stream, which may be NULL if the stream cannot be set to a new position. ASProcStmSeekProc() and ASProcStmGetLength() must be provided together. If either is NULL, the stream will not be set to a new position.

See Also

ASStmProc
ASProcStmRdOpenEx

File: ASExpT.h

Line: 536

ASProcStmSeekProc

Product availability: All

Platform availability: All

Syntax

void (*ASProcStmSeekProc)(ASFilePos64 newPos, void *clientData)

A callback for use by ASProcStmRdOpenEx().

This is called to set the stream position to a new location, which may be NULL if the stream cannot be set to a new position. ASProcStmSeekProc() and ASProcStmGetLength() must be provided together. If either is NULL, the stream will not be set to a new position.

See Also

ASStmProc
ASProcStmRdOpenEx

File: ASExpT.h

Line: 520

ASStmProc

Product availability: All

Platform availability: All

Syntax

ASTCount (*ASStmProc)(char *data, ASTArraySize nData, void *clientData)

A callback for use by ASProcStmRdOpenEx() and ASProcStmWrOpen(). This should place data in the buffer specified by the parameter data.

If your procedure reads data from a file, it is generally quite inefficient to open the file, read the bytes, and close the file each time bytes are requested. Instead, consider opening the file the first time bytes are requested from it, reading the entire file into a secondary buffer, and closing the file. When subsequent requests for data from the file are received, simply copy data from the secondary buffer, rather than reopening the file.

File: ASExpT.h

Line: 489

Method Detail

ASFileStmRdOpen

()

Product availability: All

Platform availability: All

Syntax





ASStm ASFileStmRdOpen(ASFile afile, ASSmallBufferSize bufSize)

Creates a read-only ASStm from a file. The stream supports seek operations.

Parameters

	`afile` —	The open file to associate with the stream. The file must have been opened previously using ASFileSysOpenFile(). Each open file has a unique ASFile. The ASFile value has meaning only to the common ASFile implementation and bears no relationship to platform-specific file objects.

	`bufSize` —	The length in bytes of the data buffer. If `bufSize` is `0`, the default buffer size (currently 4 K) will be used. The default is generally sufficient. A larger buffer size should be used only when data in the file will be accessed in chunks larger than the default buffer. Although `bufSize` is passed as an ASUns16, it is treated internally as an ASInt16. As a result, buffer sizes above 32 K are not permitted.

Returns

The newly created ASStm.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1064

ASFileStmWrOpen

()

Product availability: All

Platform availability: All

Syntax





ASStm ASFileStmWrOpen(ASFile afile, ASSmallBufferSize bufSize)

Creates a writable ASStm from a file. The stream supports seek operations.

Parameters

	`afile` —	The open file to associate with the stream. The file must have been opened previously using ASFileSysOpenFile(). Each open file has a unique ASFile. The ASFile value has meaning only to the common ASFile implementation and bears no relationship to platform-specific file objects.

	`bufSize` —	The length in bytes of a data buffer. If `bufSize` is `0`, the default buffer size (currently 4kB) is used. The default is generally sufficient. A larger buffer size should be used only when data in the file will be accessed in chunks larger than the default buffer. Although `bufSize` is passed as an ASUns16, it is treated internally as an ASInt16. As a result, buffer sizes above 32 K are not permitted.

Returns

The newly created ASStm.

Exceptions

genErrNoMemory

Since

PI_ACROSUPPORT_VERSION >= 0x00040000

File: ASProcs.h

Line: 1546

ASMemStmRdOpen

()

Product availability: All

Platform availability: All

Syntax





ASStm ASMemStmRdOpen(const char* data, ASArraySize len)

Creates a read-only ASStm from a memory-resident buffer. The stream supports seek operations.

Parameters

	`data` —	A buffer containing the data to read into the stream. This data buffer must not be disposed of until the ASStm is closed.

	`len` —	The length in bytes of `data`.

Returns

The newly created ASStm.

See Also

ASStmRead
ASStmClose
CosNewStream
ASMemStmRdOpen
ASProcStmRdOpenEx

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1081

ASProcStmRdOpen

()

Product availability: All

Platform availability: All

Syntax





ASStm ASProcStmRdOpen(ASStmProc readProc, void* clientData)

Creates a read-only ASStm from an arbitrary data-producing procedure. The stream does not support seek operations.

readProc is called when the client of the stream attempts to read data from it.

Parameters

	`readProc` —	A user-supplied callback that supplies the stream's data.

	`clientData` —	A pointer to user-supplied data to pass to `readProc` each time it is called.

Returns

The newly created ASStm.

Exceptions

genErrNoMemory

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1102

ASProcStmRdOpenEx

()

Product availability: All

Platform availability: All

Syntax





ASStm ASProcStmRdOpenEx(ASProcStmRdExHandler handler, void* clientData)

Extends ASProcStmRdOpen() and creates a read-only ASStm from an arbitrary data-producing procedure. The stream optionally supports seek operations, although external clients do not have the ability to initiate a seek operation.

The supplied handlers are called when the client of the stream attempts to read data from it, seek it, or find it's length, as well as when the client closes it.

Parameters

	`handler` —	A structure containing user-supplied callbacks that supply the stream's data and destroy the stream.

	`clientData` —	A pointer to user-supplied data to pass to the procedures each time they are called.

Returns

The newly created ASStm.

See Also

ASProcStmRdOpen
ASStmClose
ASStmRead

Exceptions

genErrNoMemory

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2123

ASProcStmWrOpen

()

Product availability: All

Platform availability: All

Syntax





ASStm ASProcStmWrOpen(ASStmProc writeProc, ASProcStmDestroyProc destroyProc, void* clientData)

Creates an ASStm from an arbitrary data-producing procedure. The stream does not support seek operations.

Parameters

	`writeProc` —	A user-supplied callback that provides the data for the stream.

	`destroyProc` —	A user-supplied callback that destroys the specified ASStm. (Generally, this means deallocating the memory associated with the ASStm.)

	`clientData` —	A pointer to user-supplied data to pass to `writeProc` each time it is called.

Returns

The newly created ASStm.

Exceptions

genErrNoMemory

Since

PI_ACROSUPPORT_VERSION >= 0x00040000

File: ASProcs.h

Line: 1516

ASStmClose

()

Product availability: All

Platform availability: All

Syntax





void ASStmClose(ASStm stm)

Closes the specified stream.

Parameters

stm —

The stream to close.

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1163

ASStmFlush

()

Product availability: All

Platform availability: All

Syntax





ASTCount ASStmFlush(ASStm stm)

Flushes any buffered data to the specified stream.

Parameters

stm —

The stream to flush.

Returns

0 if successful, non-zero otherwise.

See Also

ASStmClose

Since

PI_ACROSUPPORT_VERSION >= 0x00060000

File: ASProcs.h

Line: 2436

ASStmRead

()

Product availability: All

Platform availability: All

Syntax





ASTCount ASStmRead(char* ptr, ASTArraySize itemSize, ASTCount nItems, ASStm stm)

Reads data from stm into memory.

Parameters

	`ptr` —	(Filled by the method) A buffer into which data is written.

	`itemSize` —	The number of bytes in a stream item. See the description of `nItems` for further information.

	`nItems` —	The number of items to read. The amount of data read into the memory buffer will be `itemSize * nItems`, unless an EOF is encountered first. The relative values of `itemSize` and `nItems` really do not matter; the only thing that matters is their product. It is often convenient to set `itemSize` to `1`, so that `nItems` is the number of bytes to read.

	`stm` —	The stream from which data is read.

Returns

The number of items (not bytes) read.

See Also

ASStmWrite

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1122

ASStmWrite

()

Product availability: All

Platform availability: All

Syntax





ASTCount ASStmWrite(const char* ptr, ASTArraySize itemSize, ASTCount nItems, ASStm stm)

Writes data from a memory buffer into an ASStm.

You cannot use this method to change a PDF page content stream. It can only be used for a print stream. .

Historically, this method was provided to allow plug-ins to write data into the print stream when printing to a PostScript printer (see the PDDocWillPrintPage() notification). However, ASStm is a general purpose I/O mechanism in Acrobat even though only limited open and read/write methods are provided in the plug-in API. For instance, not all ASStm objects support seek operations.

Parameters

	`ptr` —	A buffer from which data is read.

	`itemSize` —	The number of bytes in a stream item. See the description of `nItems` for additional information.

	`nItems` —	The number of items to write. The amount of data written into the stream will be `itemSize * nItems`. The relative values of `itemSize` and `nItems` really do not matter; the only thing that matters is their product. It is often convenient to set `itemSize` to `1`, so that `nItems` is the number of bytes to read.

	`stm` —	The stream into which data is written.

Returns

The number of items (not bytes) written.

See Also

ASStmRead

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h

Line: 1152

Acrobat API Reference	All Layers \| All Objects \| Index \| Samples \| Frames No Frames
ASStm	Typedefs \| Structures \| Callbacks \| Methods

	ASByteCount size;

	ASStmProc readProc;

	ASProcStmDestroyProc destroyProc;

	ASProcStmSeekProc seekProc;

	ASProcStmGetLength getLengthProc;

	ASByteCount bufSize;

Layer	AS_Layer
Object	ASStm