LayerAS_Layer
ObjectASStm

An ASStm is a data stream that may be a buffer in memory, a file, or an arbitrary user-written procedure. You typically would use an ASStm to extract data from a PDF file. When writing or extracting data streams, the ASStm must be connected to a Cos stream. ASStm methods allow you to open and close streams, and to read and write data.



Typedef Summary
 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 Summary
 Structure
 _s_ASProcStmRdExHandler
For use by ASProcStmRdOpenEx().
Callback Summary
 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 Summary
 Method
 
Creates a read-only ASStm from a file. The stream supports seek operations.
 
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.

See Also


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.

See Also


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


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


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.

See Also


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.

See Also

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.

See Also

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

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.

See Also

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

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.

See Also

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.

See Also

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

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

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

Since

PI_ACROSUPPORT_VERSION >= 0x00020000

File: ASProcs.h
Line: 1152