/*
 *  @(#) 1.24 src/somext/oes/somestio.idl, somext, som3.0 6/28/96 14:33:13 [12/22/96 21:44:58]
 *
 *  COMPONENT_NAME: somext
 *
 *  ORIGINS: 27
 *
 *   25H7912  (C)  COPYRIGHT International Business Machines Corp. 1995,1996
 *  All Rights Reserved
 *  Licensed Materials - Property of IBM
 *  US Government Users Restricted Rights - Use, duplication or
 *  disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
 *
 *  DESCRIPTION:
 *
 *  This file defines the somStream module.  It is an implementation of
 *  the OMG Externalization Service.  The classes contained are:
 *
 *      StreamIO - the base implementation class (a partial implementation upon
 *              which other implementations can be built) of the CosStream::StreamIO
 *              interface.
 *      Streamable - the implementation class of the CosStream::Streamable
 *              interface.
 *      MemoryStreamIO - subclass of StreamIO.  Data is stored in compact binary
 *              representation suitable for in-memory storage.
 *      StringStreamIO - subclass of StreamIO.  Data is stored as a null terminated
 *              byte sequence representation suitable for passing as a string.
 *      StandardStreamIO - subclass of StreamIO.  Data is stored as a null terminated
 *              byte sequence representation suitable for passing as a string.
 *      Minor codes - at the end of the module are some minor codes that may
 *              be used when a system exception is raised by the externalization
 *              service.
 */

#ifndef somStream_module
#define somStream_module

#include <somos.idl>
#include <omgestio.idl>   /* D23362 */

module somStream {

  typedef sequence<octet> seq_octet;
  // This sequence type is used whenever a block of bytes needs to be passed as
  // a parameter or returned.



  interface StreamIO : CosStream::StreamIO  {
    // The StreamIO interface defines a semi-abstract class.
    // No objects of this class should be created, instead
    // use one of the stream classes derived from the StreamIO class.
    // The StreamIO interface implements the write_object and read_object methods
    // and delegates them to Stream methods externalize_ref and internalize
    // respectively.
    // All other methods from CosStream::StreamIO must be implemented by subclasses.
    // Subclasses must also implement some methods introduced by this StreamIO
    // as noted in the comments below.
    // Do not override the read/write_object/_value methods here.
    // Instead, if necessary, you should override the Stream class methods.

    enum object_tags { KeyData, RepeatRef, NilData, StringifiedRef  };
    // These tags have values 1..4.  Other tags are also allowed and they are
    // defined by the Stream implementation.
/* D23362
    readonly attribute SOMObject stream;
*/
    // If the streamio is created by the StreamFactory, then this attribute
    // will point to the stream object that "owns" this streamio.  The calls
    // to read/write_object are delegated to the containing stream.
    // If the _get_stream() method is called, and the stream attribute is not
    // set to anything (NULL), then a new somExternalization::Stream object is
    // created and returned.  The allows the read/write_object methods to work
    // even when the StreamIO has not been created by the StreamFactory.  The
    // _get_stream method may be overridden to change this behavior.
    // Note: the type of this attribute should be somExternalization::Stream,
    // but because of circular dependencies, it isn't.
/* D23362
    void write_object_tag(in octet tag, in long objnum, in CosLifeCycle::Key key);
*/
    // This method writes an object prefix to the StreamIO buffer.
    // Subclasses may or may not override.
    // The StreamIO writes key or object number for tag=1,2.
    // If the Stream passes any other tag value, the StreamIO just writes the tag
    // and ignores the other parameters.
    // Tag is one of the following values
    //   1. Object is externalized with KEY and DATA. objnum is ignored.
    //   2. Repeated Reference, use objnum. key is ignored.
    //   3. NIL object. objnum and key are ignored.
    //   4. Stringified reference objnum and key are ignored.
    // Any other value of tag: The tag is written and objnum and key are ignored.
/* D23362
    octet read_object_tag(out long objnum, out CosLifeCycle::Key key);
*/
    // This method reads an object prefix from the StreamIO buffer.
    // Subclasses may or may not override.

    boolean already_streamed( in SOMObject obj, in SOMObject class_obj);
    // This is called by Streamable objects to detect diamond top situations.

// D23362    void write_object_value(in CosStream::Streamable item);
    // This method writes the data of an object to the StreamIO.  If you call
    // write_object, the data may or may not be written to the StreamIO, depending
    // on the implementation of externalize_ref that is being used.
    // For example, if the object is has persistent references,then the Stream may
    // just write a stringified reference.  However, write_object_value will always
    // externalize the object data to the stream (using tag values 1, 2 or 3).
    // The streamable object should call write_object_value only if it "owns"
    // the object and wants to force the data to be written.
    // Note: The default implementation of write_object simply calls write_object_value.
    // More specialized Stream implementations may write something else, like
    // a stringified reference.
/* D23363
    void write_key(in CosLifeCycle::Key item);
    CosLifeCycle::Key read_key() raises(CosStream::StreamDataFormatError);
*/
    // The read/write key methods are used by read/write object tag methods
    // An implementation is provided for these which uses the read/write long
    // and string.  Subclasses may or may not override.

    void reset();
    // Reset current position in stream to the first byte.
    // Subsequent reads or writes will begin with the first byte in
    // the stream buffer.
    // This MUST be overridden by subclasses.


    void set_buffer(in seq_octet buffer);
    // Set buffer to copy of this buffer. Client should deallocate buffer.
    // The current position is reset to the first byte in the buffer.
    // This MUST be overridden by subclasses.

    seq_octet get_buffer();
    // Returns copy of buffer. Client is responsible for deallocating.
    // The size of the buffer returned to the client is also returned
    // in the length parameter.
    // This MUST be overridden by subclasses.

    void clear_buffer();
    // Empty the buffer.  Essentially makes the StreamIO just like a new one.
    // This MUST be overridden by subclasses.


    implementation {
      abstract;
      majorversion      = 3;
      minorversion      = 0;
      memory_management = corba;

      somDefaultInit:   override, init;
      somDestruct:      override;
/* D23363      override: read_object, write_object;
      stream: noget; */
      releaseorder:
        write_object_tag, read_object_tag, write_object_value, read_key, write_key,
        reset, get_buffer, set_buffer, clear_buffer, _get_stream, already_streamed,
        private1;
      dllname = "somestrm.dll";
    };
  };

// ----------------------------------------------------------------------------
  interface MemoryStreamIO : StreamIO {
    // The MemoryStreamIO interface implements two type of byte data streams.
    // One with "Big Endian" numeric values and the other with "Little
    // Endian" numeric values.  The "Little Endian" memory streams are
    // created on Intel-like machines and the "Big Endian" memory streams
    // are created on non-Intel-like machines.  These are the native
    // formats for these machines.  Both type of memory streams are
    // portable to the other machine type because byte flipping is
    // performed by the transfer_in and transfer_out methods when the
    // memory stream type is different from the native machine type.


    implementation {
      majorversion      = 3;
      minorversion      = 0;
      memory_management = corba;

      somDefaultInit:   override, init;
      somDestruct:      override;

      override: read_short, write_short,
      read_long, write_long,
      read_unsigned_short, write_unsigned_short,
      read_unsigned_long, write_unsigned_long,
      read_float, write_float,
      read_double, write_double,
      read_boolean, write_boolean,
      read_char, write_char,
      read_octet, write_octet,
      read_string, write_string,
      reset, get_buffer, set_buffer, clear_buffer;

      dllname = "somestrm.dll";
    };
  };



// ----------------------------------------------------------------------------
  interface Streamable : somOS::ServiceBase, CosStream::Streamable {
    // The Streamable interface provides an implementation of the
    // CosStream::Streamable interface.  It inherits first from ServiceBase
    // in order to get an implementation of the IdentifiableObject interface.

    implementation {
      majorversion      = 3;
      minorversion      = 0;
      memory_management = corba;

      somDefaultInit:   override, init;
      somDestruct:      override;
      dllname = "somestrm.dll";
    };
  };

//  The following minor codes are used whenever the Externalization Service
//  raises a system exception (a CORBA standard exception).

#define OES_MINOR_BASE      54000

  const long GENERAL =                          OES_MINOR_BASE + 0;
  // This is used when the exception id (name) is sufficiently descriptive.

  const long SEMAPHORE_CREATE =                 OES_MINOR_BASE + 1;
  const long SEMAPHORE_REQUEST =                OES_MINOR_BASE + 2;
  const long SEMAPHORE_RELEASE =                OES_MINOR_BASE + 3;
  // an error occurred while using a semaphore.

  const long FACTORY_FINDER_LOAD =              OES_MINOR_BASE + 4;
  // unable to load somLifeCycle DLL

  const long FACTORY_FINDER_NEW =               OES_MINOR_BASE + 5;
  // unable to create a new factory finder

  const long FACTORY_FINDER_CLASS =             OES_MINOR_BASE + 6;
  // unable to get the class of the specified factory finder

  const long FACTORY_FINDER_METHOD =            OES_MINOR_BASE + 7;
  // unable to locate the 'find_factory' method in the class.

  const long FIND_FACTORY =                     OES_MINOR_BASE + 8;
  // the find_factory method failed.

  const long NEW_NOT_STREAMABLE =               OES_MINOR_BASE + 9;
  // the new object does not support the CosStream::Streamable interface.

  const long OBJ_NOT_STREAMABLE =               OES_MINOR_BASE + 10;
  // the object does not support the CosStream::Streamable interface.

  const long FACTORY_FINDER =                   OES_MINOR_BASE + 11;
  // the factory finder parameter is not correct.

  const long METHOD_IS_ABSTRACT =               OES_MINOR_BASE + 12;
  // The method is not implemented.

  const long OBJ_REPEAT_REF_MISMATCH =          OES_MINOR_BASE + 13;
  // The parm to internalize_existing does not match repeat ref in stream.

  const long UNABLE_TO_CREATE_STREAMIO =        OES_MINOR_BASE + 14;
  // The stream is unable to create a default streamio object.

  const long STREAM_CREATE_WITH_TYPES =         OES_MINOR_BASE + 15;
  // An error occured while creating a stream-streamio with the StreamFactory

  const long UNABLE_TO_CREATE_STREAM =          OES_MINOR_BASE + 16;
  // The streamio is unable to create a default stream object.

  const long INVALID_KEY_LENGTH =               OES_MINOR_BASE + 17;
  // The parameter to write_key or write_object_tag is not valid.

  const long ALREADY_STREAMED_PARMS =           OES_MINOR_BASE + 18;
  // Parameters to already_streamed are not valid.

  const long BAD_BUFFER_PARAMETER =             OES_MINOR_BASE + 19;
  // The parm to set_buffer has invalid length or the header is incorrect.

  const long ICONV_FAILURE =                    OES_MINOR_BASE + 20;
  // An error occurred to convert the codepage of the stream data.

  const long READ_PASSED_END_OF_STREAM =        OES_MINOR_BASE + 21;
  // You attempted to read passed the end of the data in the streamio.

  const long REPEAT_REF_NUMBER_NOT_FOUND =      OES_MINOR_BASE + 22;
  // A repeat ref was read from the stream that has an invalid object number

  const long OBJ_NIL_DATA_MISMATCH =            OES_MINOR_BASE + 23;
  // A nil-data tag is found in the stream, but a non-nil object parm was passed.

  const long OBJ_STRINGIFIED_REF_MISMATCH =     OES_MINOR_BASE + 24;
  // A stringified ref found in the stream, but a non-nil object parm was passed.

  const long FOUND_UNKNOWN_TAG =                OES_MINOR_BASE + 25;
  // An unknown tag value is found in the stream.

  const long UNABLE_TO_READ_SHORT =             OES_MINOR_BASE + 26;
  const long UNABLE_TO_READ_LONG =              OES_MINOR_BASE + 27;
  const long UNABLE_TO_READ_USHORT =            OES_MINOR_BASE + 28;
  const long UNABLE_TO_READ_ULONG =             OES_MINOR_BASE + 29;
  const long UNABLE_TO_READ_STRING =            OES_MINOR_BASE + 30;
  const long UNABLE_TO_READ_CHAR =              OES_MINOR_BASE + 31;
  const long UNABLE_TO_READ_FLOAT =             OES_MINOR_BASE + 32;
  const long UNABLE_TO_READ_DOUBLE =            OES_MINOR_BASE + 33;
  const long UNABLE_TO_READ_OCTET =             OES_MINOR_BASE + 34;
  const long UNABLE_TO_READ_BOOLEAN =           OES_MINOR_BASE + 35;
  const long UNABLE_TO_READ_OBJECT =            OES_MINOR_BASE + 36;
  // The stream does not contain the correct delimiter for the specified data type.

  const long READ_FROM_EMPTY_STREAM =           OES_MINOR_BASE + 37;
  // You tried to read data from a streamio that is empty.

};

#endif /* somStream_module */

