OzStream API Description

OzStream extends the API's of OzVM to support producing a sequential stream of data. It allows data decoding algorithms to be abstracted from exterior programs.

The OzStream Exterior API allows exterior programs to open and read an OzStream as simply as a regular file. The interior program is given minimal access to system resources, only clock cycles and system memory, thus providing an implicit level of security. As a result, virii, trojans, and other security risks should not be any more prevalent in OzStreams than they are in current, non-executable formats.

The following sample code opens an OzStream file an dumps the contents to stdout. See ozcat.c for an example with verbose error reporting.

#include "ozstream.h"
#include "ozerror.h"
#include <stdio.h>

int dump_ozs( const char* filename )
{
  OzStream* osp = OzStream_open_file( filename );
  char databuf[ 4096 ];
  size_t n;

  while( ( !Oz_has_error( osp ) )
         && ( (n = OzStream_read( osp, databuf, 4096 )) > 0 ) )
  {
    fwrite( databuf, 1, n, stdout );
  }

  OzStream_close( osp );
  return Oz_has_error( osp );
}

int main( int argc, char* argv[] )
{
  if( argc != 2 )
  {
    puts("usage : dump_ozs filename");
    return 0;
  }

  OzVM_libinit();
  OzVM_specify_bootstrap_path( argv[0], 1 );

  if( dump_ozs( argv[1] ) )
    fputs( "An ERROR occured.\n", stderr );

  OzVM_libfinalize();
  return 0;
}

Table 1. OzStream Exterior API
typedef struct OzStream_struct OzStream;
An opaque data structure used as a handle to an OzStream for decoding data and detecting end-of-stream.

OzStream* OzStream_open_file( const char* filename );
Allocate and initialize an OzStream given filename. On success, the returned handle is available for reading.

OzStream* OzStream_open_vm( OzVM* vm, OzVM_read_func_type read, void* read_opaque );
Allocate and initialize an OzStream given a handle vm to an existing OzVM, a pointer to a function read that supplies the encoded data, and an opaque pointer read_opaque that is passed back into read. This function is provided as a more versatile alternative to OzStream_open_file, such as decoding data streamed over a network connection. On success, the returned handle is available for reading.

size_t OzStream_read( OzStream* osp, void* data, size_t len );
Read up to len bytes of decoded data into the buffer data from the OzStream handle osp. The actual number of bytes read is returned. The interior program is executed as necessary until the requested number of bytes are produced. So len bytes will be supplied, unless an error or end-of-stream occurs.

int OzStream_eof( OzStream* osp );
Given the OzStream handle osp, return 1 if end-of-stream has occurred for the decoded data, or 0 otherwise.

int OzStream_close( OzStream* osp );
Close and deallocate the OzStream handle osp.

OzStream* OzStream_set_read( OzStream* osp, OzVM_read_func_type read, void* read_opaque );
Given an initialized OzStream handle osp, change the function for suppling encoded data to read and its associated opaque pointer to read_opaque.

Table 1. OzStream Exterior API
typedef struct OzStream_struct OzStream; An opaque data structure used as a handle to an OzStream for decoding data and detecting end-of-stream.
OzStream* OzStream_open_file( const char* filename ); Allocate and initialize an OzStream given filename. On success, the returned handle is available for reading.
OzStream* OzStream_open_vm( OzVM* vm, OzVM_read_func_type read, void* read_opaque ); Allocate and initialize an OzStream given a handle vm to an existing OzVM, a pointer to a function read that supplies the encoded data, and an opaque pointer read_opaque that is passed back into read. This function is provided as a more versatile alternative to OzStream_open_file, such as decoding data streamed over a network connection. On success, the returned handle is available for reading.
size_t OzStream_read( OzStream* osp, void* data, size_t len ); Read up to len bytes of decoded data into the buffer data from the OzStream handle osp. The actual number of bytes read is returned. The interior program is executed as necessary until the requested number of bytes are produced. So len bytes will be supplied, unless an error or end-of-stream occurs.
int OzStream_eof( OzStream* osp ); Given the OzStream handle osp, return 1 if end-of-stream has occurred for the decoded data, or 0 otherwise.
int OzStream_close( OzStream* osp ); Close and deallocate the OzStream handle osp.
OzStream* OzStream_set_read( OzStream* osp, OzVM_read_func_type read, void* read_opaque ); Given an initialized OzStream handle osp, change the function for suppling encoded data to read and its associated opaque pointer to read_opaque.

Table 2. OzStream Interior Exports
void OZS_produce_until_eof();
This function must be exported from the interior program. The exterior program calls this function to begin production of decoded data. When using the OzStream Exterior API for access to decoded data, this is handled automatically.

Table 2. OzStream Interior Exports
void OZS_produce_until_eof(); This function must be exported from the interior program. The exterior program calls this function to begin production of decoded data. When using the OzStream Exterior API for access to decoded data, this is handled automatically.

The OzStream Interior API extends the OzVM Interior API with three new system calls. These calls input encoded data, output decoded data, and announce end-of-stream. With these functions, the interior program can have explicit, fixed memory requirements regardless of the behavior of the exterior program.

Table 3. OzStream Interior API - extensions to OzVM Interior API
System call C Prototype, Description

1024-2047 reserved for OzStream specific functions.

1024 unsigned int OZS_read( char* buffer_dst, unsigned int len );
Read up to len bytes of encoded data into buffer_dst. The actual number of bytes read is returned. A return value of 0 indicates end-of-stream for the input data.

1025 unsigned int OZS_write( char* buffer_src, unsigned int len );
Write up to len bytes of decoded data from buffer_src. The actual number of bytes written is returned.

1026 void OZS_close();
Announce end-of-stream for the decoded data.

Table 3. OzStream Interior API - extensions to OzVM Interior API
System call	C Prototype, Description
1024-2047 reserved for OzStream specific functions.
1024	unsigned int OZS_read( char* buffer_dst, unsigned int len ); Read up to len bytes of encoded data into buffer_dst. The actual number of bytes read is returned. A return value of 0 indicates end-of-stream for the input data.
1025	unsigned int OZS_write( char* buffer_src, unsigned int len ); Write up to len bytes of decoded data from buffer_src. The actual number of bytes written is returned.
1026	void OZS_close(); Announce end-of-stream for the decoded data.

$Revision: 1.1.1.1 $
$Date: 2001/09/18 10:45:25 $