home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / som30tk.zip / som30os2.zip / include / somestio.idl < prev    next >
Text File  |  1996-12-24  |  14KB  |  317 lines
  1. /*
  2.  *  @(#) 1.24 src/somext/oes/somestio.idl, somext, som3.0 6/28/96 14:33:13 [12/24/96 08:13:34]
  3.  *
  4.  *  COMPONENT_NAME: somext
  5.  *
  6.  *  ORIGINS: 27
  7.  *
  8.  *   25H7912  (C)  COPYRIGHT International Business Machines Corp. 1995,1996
  9.  *  All Rights Reserved
  10.  *  Licensed Materials - Property of IBM
  11.  *  US Government Users Restricted Rights - Use, duplication or
  12.  *  disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  13.  *
  14.  *  DESCRIPTION:
  15.  *
  16.  *  This file defines the somStream module.  It is an implementation of
  17.  *  the OMG Externalization Service.  The classes contained are:
  18.  *
  19.  *      StreamIO - the base implementation class (a partial implementation upon
  20.  *              which other implementations can be built) of the CosStream::StreamIO
  21.  *              interface.
  22.  *      Streamable - the implementation class of the CosStream::Streamable
  23.  *              interface.
  24.  *      MemoryStreamIO - subclass of StreamIO.  Data is stored in compact binary
  25.  *              representation suitable for in-memory storage.
  26.  *      StringStreamIO - subclass of StreamIO.  Data is stored as a null terminated
  27.  *              byte sequence representation suitable for passing as a string.
  28.  *      StandardStreamIO - subclass of StreamIO.  Data is stored as a null terminated
  29.  *              byte sequence representation suitable for passing as a string.
  30.  *      Minor codes - at the end of the module are some minor codes that may
  31.  *              be used when a system exception is raised by the externalization
  32.  *              service.
  33.  */
  34.  
  35. #ifndef somStream_module
  36. #define somStream_module
  37.  
  38. #include <somos.idl>
  39. #include <omgestio.idl>   /* D23362 */
  40.  
  41. module somStream {
  42.  
  43.   typedef sequence<octet> seq_octet;
  44.   // This sequence type is used whenever a block of bytes needs to be passed as
  45.   // a parameter or returned.
  46.  
  47.  
  48.  
  49.   interface StreamIO : CosStream::StreamIO  {
  50.     // The StreamIO interface defines a semi-abstract class.
  51.     // No objects of this class should be created, instead
  52.     // use one of the stream classes derived from the StreamIO class.
  53.     // The StreamIO interface implements the write_object and read_object methods
  54.     // and delegates them to Stream methods externalize_ref and internalize
  55.     // respectively.
  56.     // All other methods from CosStream::StreamIO must be implemented by subclasses.
  57.     // Subclasses must also implement some methods introduced by this StreamIO
  58.     // as noted in the comments below.
  59.     // Do not override the read/write_object/_value methods here.
  60.     // Instead, if necessary, you should override the Stream class methods.
  61.  
  62.     enum object_tags { KeyData, RepeatRef, NilData, StringifiedRef  };
  63.     // These tags have values 1..4.  Other tags are also allowed and they are
  64.     // defined by the Stream implementation.
  65. /* D23362
  66.     readonly attribute SOMObject stream;
  67. */
  68.     // If the streamio is created by the StreamFactory, then this attribute
  69.     // will point to the stream object that "owns" this streamio.  The calls
  70.     // to read/write_object are delegated to the containing stream.
  71.     // If the _get_stream() method is called, and the stream attribute is not
  72.     // set to anything (NULL), then a new somExternalization::Stream object is
  73.     // created and returned.  The allows the read/write_object methods to work
  74.     // even when the StreamIO has not been created by the StreamFactory.  The
  75.     // _get_stream method may be overridden to change this behavior.
  76.     // Note: the type of this attribute should be somExternalization::Stream,
  77.     // but because of circular dependencies, it isn't.
  78. /* D23362
  79.     void write_object_tag(in octet tag, in long objnum, in CosLifeCycle::Key key);
  80. */
  81.     // This method writes an object prefix to the StreamIO buffer.
  82.     // Subclasses may or may not override.
  83.     // The StreamIO writes key or object number for tag=1,2.
  84.     // If the Stream passes any other tag value, the StreamIO just writes the tag
  85.     // and ignores the other parameters.
  86.     // Tag is one of the following values
  87.     //   1. Object is externalized with KEY and DATA. objnum is ignored.
  88.     //   2. Repeated Reference, use objnum. key is ignored.
  89.     //   3. NIL object. objnum and key are ignored.
  90.     //   4. Stringified reference objnum and key are ignored.
  91.     // Any other value of tag: The tag is written and objnum and key are ignored.
  92. /* D23362
  93.     octet read_object_tag(out long objnum, out CosLifeCycle::Key key);
  94. */
  95.     // This method reads an object prefix from the StreamIO buffer.
  96.     // Subclasses may or may not override.
  97.  
  98.     boolean already_streamed( in SOMObject obj, in SOMObject class_obj);
  99.     // This is called by Streamable objects to detect diamond top situations.
  100.  
  101. // D23362    void write_object_value(in CosStream::Streamable item);
  102.     // This method writes the data of an object to the StreamIO.  If you call
  103.     // write_object, the data may or may not be written to the StreamIO, depending
  104.     // on the implementation of externalize_ref that is being used.
  105.     // For example, if the object is has persistent references,then the Stream may
  106.     // just write a stringified reference.  However, write_object_value will always
  107.     // externalize the object data to the stream (using tag values 1, 2 or 3).
  108.     // The streamable object should call write_object_value only if it "owns"
  109.     // the object and wants to force the data to be written.
  110.     // Note: The default implementation of write_object simply calls write_object_value.
  111.     // More specialized Stream implementations may write something else, like
  112.     // a stringified reference.
  113. /* D23363
  114.     void write_key(in CosLifeCycle::Key item);
  115.     CosLifeCycle::Key read_key() raises(CosStream::StreamDataFormatError);
  116. */
  117.     // The read/write key methods are used by read/write object tag methods
  118.     // An implementation is provided for these which uses the read/write long
  119.     // and string.  Subclasses may or may not override.
  120.  
  121.     void reset();
  122.     // Reset current position in stream to the first byte.
  123.     // Subsequent reads or writes will begin with the first byte in
  124.     // the stream buffer.
  125.     // This MUST be overridden by subclasses.
  126.  
  127.  
  128.     void set_buffer(in seq_octet buffer);
  129.     // Set buffer to copy of this buffer. Client should deallocate buffer.
  130.     // The current position is reset to the first byte in the buffer.
  131.     // This MUST be overridden by subclasses.
  132.  
  133.     seq_octet get_buffer();
  134.     // Returns copy of buffer. Client is responsible for deallocating.
  135.     // The size of the buffer returned to the client is also returned
  136.     // in the length parameter.
  137.     // This MUST be overridden by subclasses.
  138.  
  139.     void clear_buffer();
  140.     // Empty the buffer.  Essentially makes the StreamIO just like a new one.
  141.     // This MUST be overridden by subclasses.
  142.  
  143.  
  144.     implementation {
  145.       abstract;
  146.       majorversion      = 3;
  147.       minorversion      = 0;
  148.       memory_management = corba;
  149.  
  150.       somDefaultInit:   override, init;
  151.       somDestruct:      override;
  152. /* D23363      override: read_object, write_object;
  153.       stream: noget; */
  154.       releaseorder:
  155.         write_object_tag, read_object_tag, write_object_value, read_key, write_key,
  156.         reset, get_buffer, set_buffer, clear_buffer, _get_stream, already_streamed,
  157.         private1;
  158.       dllname = "somestrm.dll";
  159.     };
  160.   };
  161.  
  162. // ----------------------------------------------------------------------------
  163.   interface MemoryStreamIO : StreamIO {
  164.     // The MemoryStreamIO interface implements two type of byte data streams.
  165.     // One with "Big Endian" numeric values and the other with "Little
  166.     // Endian" numeric values.  The "Little Endian" memory streams are
  167.     // created on Intel-like machines and the "Big Endian" memory streams
  168.     // are created on non-Intel-like machines.  These are the native
  169.     // formats for these machines.  Both type of memory streams are
  170.     // portable to the other machine type because byte flipping is
  171.     // performed by the transfer_in and transfer_out methods when the
  172.     // memory stream type is different from the native machine type.
  173.  
  174.  
  175.     implementation {
  176.       majorversion      = 3;
  177.       minorversion      = 0;
  178.       memory_management = corba;
  179.  
  180.       somDefaultInit:   override, init;
  181.       somDestruct:      override;
  182.  
  183.       override: read_short, write_short,
  184.       read_long, write_long,
  185.       read_unsigned_short, write_unsigned_short,
  186.       read_unsigned_long, write_unsigned_long,
  187.       read_float, write_float,
  188.       read_double, write_double,
  189.       read_boolean, write_boolean,
  190.       read_char, write_char,
  191.       read_octet, write_octet,
  192.       read_string, write_string,
  193.       reset, get_buffer, set_buffer, clear_buffer;
  194.  
  195.       dllname = "somestrm.dll";
  196.     };
  197.   };
  198.  
  199.  
  200.  
  201. // ----------------------------------------------------------------------------
  202.   interface Streamable : somOS::ServiceBase, CosStream::Streamable {
  203.     // The Streamable interface provides an implementation of the
  204.     // CosStream::Streamable interface.  It inherits first from ServiceBase
  205.     // in order to get an implementation of the IdentifiableObject interface.
  206.  
  207.     implementation {
  208.       majorversion      = 3;
  209.       minorversion      = 0;
  210.       memory_management = corba;
  211.  
  212.       somDefaultInit:   override, init;
  213.       somDestruct:      override;
  214.       dllname = "somestrm.dll";
  215.     };
  216.   };
  217.  
  218. //  The following minor codes are used whenever the Externalization Service
  219. //  raises a system exception (a CORBA standard exception).
  220.  
  221. #define OES_MINOR_BASE      54000
  222.  
  223.   const long GENERAL =                          OES_MINOR_BASE + 0;
  224.   // This is used when the exception id (name) is sufficiently descriptive.
  225.  
  226.   const long SEMAPHORE_CREATE =                 OES_MINOR_BASE + 1;
  227.   const long SEMAPHORE_REQUEST =                OES_MINOR_BASE + 2;
  228.   const long SEMAPHORE_RELEASE =                OES_MINOR_BASE + 3;
  229.   // an error occurred while using a semaphore.
  230.  
  231.   const long FACTORY_FINDER_LOAD =              OES_MINOR_BASE + 4;
  232.   // unable to load somLifeCycle DLL
  233.  
  234.   const long FACTORY_FINDER_NEW =               OES_MINOR_BASE + 5;
  235.   // unable to create a new factory finder
  236.  
  237.   const long FACTORY_FINDER_CLASS =             OES_MINOR_BASE + 6;
  238.   // unable to get the class of the specified factory finder
  239.  
  240.   const long FACTORY_FINDER_METHOD =            OES_MINOR_BASE + 7;
  241.   // unable to locate the 'find_factory' method in the class.
  242.  
  243.   const long FIND_FACTORY =                     OES_MINOR_BASE + 8;
  244.   // the find_factory method failed.
  245.  
  246.   const long NEW_NOT_STREAMABLE =               OES_MINOR_BASE + 9;
  247.   // the new object does not support the CosStream::Streamable interface.
  248.  
  249.   const long OBJ_NOT_STREAMABLE =               OES_MINOR_BASE + 10;
  250.   // the object does not support the CosStream::Streamable interface.
  251.  
  252.   const long FACTORY_FINDER =                   OES_MINOR_BASE + 11;
  253.   // the factory finder parameter is not correct.
  254.  
  255.   const long METHOD_IS_ABSTRACT =               OES_MINOR_BASE + 12;
  256.   // The method is not implemented.
  257.  
  258.   const long OBJ_REPEAT_REF_MISMATCH =          OES_MINOR_BASE + 13;
  259.   // The parm to internalize_existing does not match repeat ref in stream.
  260.  
  261.   const long UNABLE_TO_CREATE_STREAMIO =        OES_MINOR_BASE + 14;
  262.   // The stream is unable to create a default streamio object.
  263.  
  264.   const long STREAM_CREATE_WITH_TYPES =         OES_MINOR_BASE + 15;
  265.   // An error occured while creating a stream-streamio with the StreamFactory
  266.  
  267.   const long UNABLE_TO_CREATE_STREAM =          OES_MINOR_BASE + 16;
  268.   // The streamio is unable to create a default stream object.
  269.  
  270.   const long INVALID_KEY_LENGTH =               OES_MINOR_BASE + 17;
  271.   // The parameter to write_key or write_object_tag is not valid.
  272.  
  273.   const long ALREADY_STREAMED_PARMS =           OES_MINOR_BASE + 18;
  274.   // Parameters to already_streamed are not valid.
  275.  
  276.   const long BAD_BUFFER_PARAMETER =             OES_MINOR_BASE + 19;
  277.   // The parm to set_buffer has invalid length or the header is incorrect.
  278.  
  279.   const long ICONV_FAILURE =                    OES_MINOR_BASE + 20;
  280.   // An error occurred to convert the codepage of the stream data.
  281.  
  282.   const long READ_PASSED_END_OF_STREAM =        OES_MINOR_BASE + 21;
  283.   // You attempted to read passed the end of the data in the streamio.
  284.  
  285.   const long REPEAT_REF_NUMBER_NOT_FOUND =      OES_MINOR_BASE + 22;
  286.   // A repeat ref was read from the stream that has an invalid object number
  287.  
  288.   const long OBJ_NIL_DATA_MISMATCH =            OES_MINOR_BASE + 23;
  289.   // A nil-data tag is found in the stream, but a non-nil object parm was passed.
  290.  
  291.   const long OBJ_STRINGIFIED_REF_MISMATCH =     OES_MINOR_BASE + 24;
  292.   // A stringified ref found in the stream, but a non-nil object parm was passed.
  293.  
  294.   const long FOUND_UNKNOWN_TAG =                OES_MINOR_BASE + 25;
  295.   // An unknown tag value is found in the stream.
  296.  
  297.   const long UNABLE_TO_READ_SHORT =             OES_MINOR_BASE + 26;
  298.   const long UNABLE_TO_READ_LONG =              OES_MINOR_BASE + 27;
  299.   const long UNABLE_TO_READ_USHORT =            OES_MINOR_BASE + 28;
  300.   const long UNABLE_TO_READ_ULONG =             OES_MINOR_BASE + 29;
  301.   const long UNABLE_TO_READ_STRING =            OES_MINOR_BASE + 30;
  302.   const long UNABLE_TO_READ_CHAR =              OES_MINOR_BASE + 31;
  303.   const long UNABLE_TO_READ_FLOAT =             OES_MINOR_BASE + 32;
  304.   const long UNABLE_TO_READ_DOUBLE =            OES_MINOR_BASE + 33;
  305.   const long UNABLE_TO_READ_OCTET =             OES_MINOR_BASE + 34;
  306.   const long UNABLE_TO_READ_BOOLEAN =           OES_MINOR_BASE + 35;
  307.   const long UNABLE_TO_READ_OBJECT =            OES_MINOR_BASE + 36;
  308.   // The stream does not contain the correct delimiter for the specified data type.
  309.  
  310.   const long READ_FROM_EMPTY_STREAM =           OES_MINOR_BASE + 37;
  311.   // You tried to read data from a streamio that is empty.
  312.  
  313. };
  314.  
  315. #endif /* somStream_module */
  316.  
  317.