Output Struct Reference

Inheritance diagram for Output

Inheritance graph


Public Methods

long Output_seekp (struct Output *ptr_output, long pos, seek_t mode)
long Output_tellp (struct Output *ptr_output)
long Output_write (struct Output *ptr_output, void *buffer, long length)
int Output_write_byte (struct Output *ptr_output, int byte)
int Output_get_flags (struct Output *ptr_output)
bool Output_is_eof (struct Output *ptr_output)
bool Output_is_bad (struct Output *ptr_output)
bool Output_is_good (struct Output *ptr_output)
long Output_get_size (struct Output *ptr_output)
void Output_dtor (struct Output *ptr_output, int)
short Output_write_word (struct Output *ptr_output, short word)
long Output_write_dword (struct Output *ptr_output, long dword)

Detailed Description

The CyOS's stream modes have two basic streams that are abstractions for the sequential data access objects: Input and Output. Those streams can pump data to and from virtually any source, including disk file, network connection, console terminals and more. Those basic streams are used, in turn, with filter streams, that apply specific features to some abstract streams' filters.

Typical stream implementations include the file streams FileInput and FileOutput, console streams and various filters. Filter streams process the data from other streams. They take the other stream's objects while constructing, and are just like regular streams themselves. Typical filters are UNICODE/ASCII conversion, text formatting streams Reader and Writer and compressing streams Compressor and Decompressor.

Filters are intended to combine the desired stream implementation with the selected filter object, to combine the features that best suit your needs. This object is just an interface for an input stream.

See also:
File I/O

Member Function Documentation

void Output_dtor ( struct Output * ptr_output,
int memory_flag )
 

Destructor.

Parameters:
ptr_output   A pointer to the initialized Output object
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY If the object was static or allocated in a stack
Returns:
None 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
FREE_MEMORY, LEAVE_MEMORY.

int Output_get_flags ( struct Output * ptr_output )
 

Returns the current flags.

Parameters:
ptr_output   A pointer to the initialized Output object
Returns:
Current flags 
       #include <cywin.h>
       ...
       char obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char current_value;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       while( !( Output_get_flags(ptr_output) & FLAG_EOF ) )
       {
         current_value = obtain_new_value();
         Output_write_byte( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

long Output_get_size ( struct Output * ptr_output )
 

Returns the stream size (if applicable).

Parameters:
ptr_output   A pointer to the initialized Output object
Returns:
Stream size, or -1 if the operation can't be done on this stream 
       #include <cywin.h>
       ...
       char obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output );
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_byte( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

bool Output_is_bad ( struct Output * ptr_output )
 

Returns TRUE if the BAD flag is set (stream is bad).

Parameters:
ptr_output   A pointer to the initialized Output object
Returns:
TRUE if the BAD flag is set (stream is bad) 
       #include <cywin.h>
       ...
       struct Output *ptr_output;
       ...
       Output_ctor_Ex(ptr_output, "game.save");
       if (!FileOutput_is_bad(ptr_output))
       {
         //success
       }
       ...
       Output_dtor( ptr_output, LEAVE_MEMORY );
See also:
Output_is_good, Output_is_eof.

bool Output_is_eof ( struct Output * ptr_output )
 

Returns TRUE if the EOF flag is set (stream reached end-of-file).

Parameters:
ptr_output   A pointer to the initialized Output object
Returns:
TRUE if the EOF flag is set (stream reached end-of-file) 
   #include <cywin.h>
   ...
   char obtain_new_value();
   ...
   struct module_t main_module;
   struct Output* ptr_output;
   char current_value;
   ...
   ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                       "data.txt" );
   ...
   while( !( Output_is_eof(ptr_output))
   {
     current_value = obtain_new_value();
     Output_write_byte( ptr_output, current_value );
   }
   ...
   Output_dtor( ptr_output, FREE_MEMORY );
   ...
See also:
Output_is_good, Output_is_bad.

bool Output_is_good ( struct Output * ptr_output )
 

Returns TRUE if the BAD flag is not set (stream is good).

Parameters:
ptr_output   A pointer to the initialized Output object
Returns:
TRUE if the BAD flag is not set (stream is good) 
       #include <cywin.h>
       ...
       struct Output *file_output;
       ...
       Output_ctor_Ex(file_output, "game.save");
       if (FileOutput_is_good(file_output))
       {
         //success
       }
       ...
       Output_dtor( &file_output, LEAVE_MEMORY );
See also:
Output_is_eof, Output_is_bad.

long Output_seekp ( struct Output * ptr_output,
long pos,
seek_t mode )
 

Seeks an output stream.
If the stream supports a seek operation, it seeks to the specified position in the specified mode. If the requested seek operation cannot be done (not supported or wrong parameters), -1 will be returned. Seeking prior to the beginning of the stream sets the pointer to the stream's first byte. Seeking after the end of the stream sets the pointer to the end of the stream; then the stream will be extended with garbage bytes to the specified size.

Parameters:
ptr_output   A pointer to the initialized Output object
pos   The seek offset
mode   The seek mode
Returns:
The new position, or -1 if an error occurred 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

long Output_tellp ( struct Output * ptr_output )
 

Returns the stream's position.

Parameters:
ptr_output   A pointer to the initialized Output object
Returns:
The stream's position, or -1 if that operation is not supported for this stream 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       long cur_pos;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       // cur_pos will be equal to 11.
       cur_pos = Output_tellp( ptr_output );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...

long Output_write ( struct Output * ptr_output,
void * buffer,
long length )
 

Writes the 'length' bytes to the stream.

Parameters:
ptr_output   A pointer to the initialized Output object
buffer   Where to get the data
length   The number of bytes to be written
Returns:
The actual number of written bytes; may be less that than 'length' or even zero 
       #include <cywin.h>
       #include "score.h"
       ...
       struct Input* ptr_input;
       struct score_t high_scores[10];
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       long cur_pos;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_write( ptr_output, high_scores, sizeof( high_scores ) );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write_byte.

int Output_write_byte ( struct Output * ptr_output,
int byte )
 

Writes a byte to the stream.

Parameters:
ptr_output   A pointer to the initialized Output object
byte   Determines which byte to write
Returns:
-1 if the process fails, the parameter's value if it succeeds 
       #include <cywin.h>
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       char tenth_byte = 100;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       Output_seekp( ptr_output, 10, SEEK_SET );
       Output_write_byte( ptr_output, tenth_byte );
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write.

long Output_write_dword ( struct Output * ptr_output,
long dword )
 

Writes a 32-bit word, independent of hardware.

Parameters:
ptr_output   A pointer to the initialized Output object
dword   A dword to be written
Returns:
-1 if the process fails, the parameter's value if it succeeds 
       #include <cywin.h>
       ...
       long obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       long current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output )/sizeof(long);
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_dword( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write_word.

short Output_write_word ( struct Output * ptr_output,
short word )
 

Writes a 16-bit word, independent of hardware.

Parameters:
ptr_output   A pointer to the initialized Output object
word   A word to be written
Returns:
-1 if the process fails, the parameter's value if it succeeds 
       #include <cywin.h>
       ...
       int obtain_new_value();
       ...
       struct module_t main_module;
       struct Output* ptr_output;
       int current_value;
       long size;
       ...
       ptr_output = Archive_open_write_Ex ( main_module.m_process->module->archive,
                                           "data.txt" );
       ...
       size = Output_get_size( ptr_output )/sizeof(int);
       for( index = 0; index < size; index++ )
       {
         current_value = obtain_new_value();
         Output_write_word( ptr_output, current_value );
       }
       ...
       Output_dtor( ptr_output, FREE_MEMORY );
       ...
See also:
Output_write_dword.