CDR.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    CDR.h
00006  *
00007  *  $Id: CDR.h 80289 2007-12-17 20:34:44Z johnnyw $
00008  *
00009  *   Common Data Representation (CDR) marshaling streams.
00010  *
00011  *   This implementation assumes that the native numeric
00012  *   representation is two's complement for integers, IEEE
00013  *   single/double for floats.  Also that characters are in ISO
00014  *   Latin/1.
00015  *
00016  *   Note that CDR itself makes no such assumptions, but this
00017  *   implementation makes such assumptions for reasons of
00018  *   efficiency.  Careful enhancements could preserve that
00019  *   efficiency where the assumptions are true, yet still allow the
00020  *   code to work when they aren't true.
00021  *
00022  *   The implementation expects that buffers are aligned according
00023  *   to the strongest CDR alignment restriction.
00024  *
00025  *   NOTE: this does everything "CDR 1.1" does ... that is, it
00026  *   supports the five extended OMG-IDL data types in UNO Appendix
00027  *   A, which provide richer arithmetic types (64 bit integers,
00028  *   "quad precision" FP) and UNICODE-based characters and strings.
00029  *   Those types are not standard parts of OMG-IDL at this time.
00030  *
00031  *   THREADING NOTE: CDR data structures must be protected against
00032  *   concurrent access by their owning thread.
00033  *
00034  *
00035  *  @author  Copyright 1994-1995 by Sun Microsystems Inc.
00036  *  @author  Aniruddha Gokhale
00037  *  @author  Carlos O'Ryan
00038  */
00039 //=============================================================================
00040 
00041 
00042 #ifndef TAO_CDR_H
00043 #define TAO_CDR_H
00044 
00045 #include /**/ "ace/pre.h"
00046 
00047 #include "tao/orbconf.h"
00048 
00049 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00050 # pragma once
00051 #endif /* ACE_LACKS_PRAGMA_ONCE */
00052 
00053 #include /**/ "tao/TAO_Export.h"
00054 #include "tao/Basic_Types.h"
00055 #include "tao/GIOP_Message_Version.h"
00056 #include "tao/Transport.h"
00057 
00058 #include "ace/CDR_Stream.h"
00059 
00060 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
00061 
00062 class TAO_ORB_Core;
00063 class TAO_GIOP_Fragmentation_Strategy;
00064 class TAO_Stub;
00065 
00066 /**
00067  * @class TAO_OutputCDR
00068  *
00069  * @brief A CDR stream for writing, i.e. for marshalling.
00070  *
00071  * This class is based on the the CORBA spec for Java (98-02-29),
00072  * java class omg.org.CORBA.portable.OutputStream.
00073  * It diverts in a few ways:
00074  * + Operations taking arrays don't have offsets, because in C++
00075  * it is easier to describe an array starting from x+offset.
00076  * + Operations return an error status, because exceptions are
00077  * not widely available in C++ (yet).
00078  * A particularly useful static member function for this buffer is
00079  * an interpretive encoding routine, usable as a typecode
00080  * interpreter callback.  Ditto for decoding.  These are used to
00081  * support all OMG-IDL datatypes, even those not supported
00082  * directly by put/get primitives.
00083  */
00084 class TAO_Export TAO_OutputCDR : public ACE_OutputCDR
00085 {
00086 public:
00087   /// For reading from a output CDR stream.
00088   friend class TAO_InputCDR;
00089 
00090   // The default values for the allocators and memcpy_tradeoff
00091   // in these constructors are not 0, but are generated by the
00092   // ORB. Refer to the constructor bodies in CDR.cpp for the
00093   // code that supplies these values to the base class constructor.
00094 
00095   /// Default constructor, allocates <size> bytes in the internal
00096   /// buffer, if <size> == 0 it allocates the default size.
00097   TAO_OutputCDR (size_t size = 0,
00098                  int byte_order = ACE_CDR_BYTE_ORDER,
00099                  ACE_Allocator* buffer_allocator = 0,
00100                  ACE_Allocator* data_block_allocator = 0,
00101                  ACE_Allocator* message_block_allocator = 0,
00102                  size_t memcpy_tradeoff = 0,
00103                  ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00104                  ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR);
00105 
00106   /// Build a CDR stream with an initial buffer, it will *not* remove
00107   /// <data>, since it did not allocated it.
00108   TAO_OutputCDR (char *data,
00109                  size_t size,
00110                  int byte_order = ACE_CDR_BYTE_ORDER,
00111                  ACE_Allocator* buffer_allocator = 0,
00112                  ACE_Allocator* data_block_allocator = 0,
00113                  ACE_Allocator* message_block_allocator = 0,
00114                  size_t memcpy_tradeoff = 0,
00115                  ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00116                  ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR);
00117 
00118   /// Build a CDR stream with an initial buffer, it will *not* remove
00119   /// @a data since it did not allocated it, and enable fragmentation
00120   /// support.
00121   TAO_OutputCDR (char *data,
00122                  size_t size,
00123                  int byte_order,
00124                  ACE_Allocator* buffer_allocator,
00125                  ACE_Allocator* data_block_allocator,
00126                  ACE_Allocator* message_block_allocator,
00127                  size_t memcpy_tradeoff,
00128                  TAO_GIOP_Fragmentation_Strategy * fs,
00129                  ACE_CDR::Octet major_version,
00130                  ACE_CDR::Octet minor_version);
00131 
00132   /// Build a CDR stream with an initial Message_Block chain, it will *not*
00133   /// remove <data>, since it did not allocate it.
00134   TAO_OutputCDR (ACE_Message_Block *data,
00135                  int byte_order = ACE_CDR_BYTE_ORDER,
00136                  size_t memcpy_tradeoff = 0,
00137                  ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00138                  ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR);
00139 
00140   /// Build a CDR stream with an initial data block, it will *not* remove
00141   /// <data_block>, since it did not allocated it.
00142   TAO_OutputCDR (ACE_Data_Block *data,
00143                  int byte_order = ACE_CDR_BYTE_ORDER,
00144                  ACE_Allocator* message_block_allocator = 0,
00145                  size_t memcpy_tradeoff = 0,
00146                  TAO_GIOP_Fragmentation_Strategy * fs = 0,
00147                  ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00148                  ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR);
00149 
00150   /// Destructor.
00151   ~TAO_OutputCDR (void);
00152 
00153   // @todo do we want a special method to write an array of
00154   // strings and wstrings?
00155 
00156   // = TAO specific methods.
00157   static void throw_stub_exception (int error_num);
00158   static void throw_skel_exception (int error_num);
00159 
00160   void get_version (TAO_GIOP_Message_Version& giop_version);
00161 
00162   /**
00163    * @name Outgoing GIOP Fragment Related Methods
00164    *
00165    * These methods are only used when fragmenting outgoing GIOP
00166    * requests and replies.
00167    */
00168   //@{
00169   /// Fragment this output CDR stream if necessary.
00170   /**
00171    * Fragmentation will done through GIOP fragments when the length of
00172    * the CDR stream length will exceed the configured threshold.
00173    */
00174   bool fragment_stream (ACE_CDR::ULong pending_alignment,
00175                         ACE_CDR::ULong pending_length);
00176 
00177   /// Are there more data fragments to come?
00178   bool more_fragments (void) const;
00179 
00180   /// Specify whether there are more data fragments to come.
00181   void more_fragments (bool more);
00182 
00183   /// Set fragmented message attributes.
00184   void message_attributes (CORBA::ULong request_id,
00185                            TAO_Stub * stub,
00186                            TAO_Transport::TAO_Message_Semantics message_semantics,
00187                            ACE_Time_Value * timeout);
00188 
00189   /// Fragmented message request ID.
00190   CORBA::ULong request_id (void) const;
00191 
00192   /// Stub object associated with the request.
00193   TAO_Stub * stub (void) const;
00194 
00195   /// Message semantics (twoway, oneway, reply)
00196   TAO_Transport::TAO_Message_Semantics message_semantics (void) const;
00197 
00198   /// Maximum time to wait for outgoing message to be sent.
00199   ACE_Time_Value * timeout (void) const;
00200   //@}
00201 
00202 private:
00203 
00204   // disallow copying...
00205   TAO_OutputCDR (const TAO_OutputCDR& rhs);
00206   TAO_OutputCDR& operator= (const TAO_OutputCDR& rhs);
00207 
00208 private:
00209 
00210   /**
00211    * @name Outgoing GIOP Fragment Related Attributes
00212    *
00213    * These attributes are only used when fragmenting outgoing GIOP
00214    * requests and replies.
00215    */
00216   //@{
00217   /// Strategy that sends data currently marshaled into this
00218   /// TAO_OutputCDR stream if necessary.
00219   TAO_GIOP_Fragmentation_Strategy * const fragmentation_strategy_;
00220 
00221   /// Are there more data fragments to come?
00222   bool more_fragments_;
00223 
00224   /// Request ID for the request currently being marshaled.
00225   CORBA::ULong request_id_;
00226 
00227   /// Stub object associated with the request.
00228   TAO_Stub * stub_;
00229 
00230   /// Twoway, oneway, reply?
00231   /**
00232    * @see TAO_Transport
00233    */
00234   TAO_Transport::TAO_Message_Semantics message_semantics_;
00235 
00236   /// Request/reply send timeout.
00237   ACE_Time_Value * timeout_;
00238   //@}
00239 
00240 };
00241 
00242 /**
00243  * @class TAO_InputCDR
00244  *
00245  * @brief A CDR stream for reading, i.e. for demarshalling.
00246  *
00247  * This class is based on the the CORBA spec for Java (98-02-29),
00248  * java class omg.org.CORBA.portable.InputStream.
00249  * It diverts in a few ways:
00250  * + Operations to retrieve basic types take parameters by
00251  * reference.
00252  * + Operations taking arrays don't have offsets, because in C++
00253  * it is easier to describe an array starting from x+offset.
00254  * + Operations return an error status, because exceptions are
00255  * not widely available in C++ (yet).
00256  * A particularly useful static member function for this buffer is
00257  * an interpretive encoding routine, usable as a typecode
00258  * interpreter callback.  Ditto for decoding.  These are used to
00259  * support all OMG-IDL datatypes, even those not supported
00260  * directly by put/get primitives.
00261  */
00262 class TAO_Export TAO_InputCDR : public ACE_InputCDR
00263 {
00264 public:
00265   /**
00266    * Create an input stream from an arbitrary buffer, care must be
00267    * exercised wrt alignment, because this contructor will *not* work
00268    * if the buffer is unproperly aligned.
00269    */
00270   TAO_InputCDR (const char* buf,
00271                 size_t bufsiz,
00272                 int byte_order = ACE_CDR_BYTE_ORDER,
00273                 ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00274                 ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR,
00275                 TAO_ORB_Core* orb_core = 0);
00276 
00277   /// Create an empty input stream. The caller is responsible for
00278   /// putting the right data and providing the right alignment.
00279   TAO_InputCDR (size_t bufsiz,
00280                 int byte_order = ACE_CDR_BYTE_ORDER,
00281                 ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00282                 ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR,
00283                 TAO_ORB_Core* orb_core = 0);
00284 
00285   /// Create an input stream from an ACE_Message_Block
00286   TAO_InputCDR (const ACE_Message_Block *data,
00287                 int byte_order = ACE_CDR_BYTE_ORDER,
00288                 ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00289                 ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR,
00290                 TAO_ORB_Core* orb_core = 0);
00291 
00292   /// Create an input stream from an ACE_Message_Block with an optional lock
00293   /// used to protect the data.
00294   TAO_InputCDR (const ACE_Message_Block *data,
00295                 ACE_Lock* lock,
00296                 int byte_order = ACE_CDR_BYTE_ORDER,
00297                 ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00298                 ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR,
00299                 TAO_ORB_Core* orb_core = 0);
00300 
00301 
00302   /// Create an input stream from an ACE_Data_Block
00303   TAO_InputCDR (ACE_Data_Block *data,
00304                 ACE_Message_Block::Message_Flags flag = 0,
00305                 int byte_order = ACE_CDR_BYTE_ORDER,
00306                 ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00307                 ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR,
00308                 TAO_ORB_Core* orb_core = 0);
00309 
00310   /// Create an input stream from an ACE_Data_Block
00311   TAO_InputCDR (ACE_Data_Block *data,
00312                 ACE_Message_Block::Message_Flags flag,
00313                 size_t read_pointer_position,
00314                 size_t write_pointer_position,
00315                 int byte_order = ACE_CDR_BYTE_ORDER,
00316                 ACE_CDR::Octet major_version = TAO_DEF_GIOP_MAJOR,
00317                 ACE_CDR::Octet minor_version = TAO_DEF_GIOP_MINOR,
00318                 TAO_ORB_Core* orb_core = 0);
00319 
00320   /**
00321    * Make a copy of the current stream state, but does not copy the
00322    * internal buffer; so the same stream can be read multiple times
00323    * efficiently.
00324    */
00325   TAO_InputCDR (const TAO_InputCDR& rhs);
00326 
00327   /// When interpreting indirected TypeCodes it is useful to make a
00328   /// "copy" of the stream starting in the new position.
00329   TAO_InputCDR (const TAO_InputCDR& rhs,
00330                 size_t size,
00331                 ACE_CDR::Long offset);
00332   /**
00333    * This creates an encapsulated stream, the first byte must be (per
00334    * the spec) the byte order of the encapsulation.  The default
00335    * values for the allocators in this constructor are not 0, but are
00336    * generated by the ORB. Refer to the constructor body in CDR.cpp
00337    * for the code that supplies these values to the base class
00338    * constructor.
00339    */
00340   TAO_InputCDR (const TAO_InputCDR& rhs,
00341                 size_t size);
00342 
00343   /// Create an input CDR from an output CDR.
00344   TAO_InputCDR (const TAO_OutputCDR& rhs,
00345                 ACE_Allocator* buffer_allocator = 0,
00346                 ACE_Allocator* data_block_allocator = 0,
00347                 ACE_Allocator* message_block_allocator = 0,
00348                 TAO_ORB_Core* orb_core = 0);
00349 
00350   /// Initialize the contents of one CDR from another, without data
00351   /// copying and with minimimum locking overhead.
00352   TAO_InputCDR (ACE_InputCDR::Transfer_Contents rhs,
00353                 TAO_ORB_Core* orb_core = 0);
00354 
00355   /// destructor
00356   ~TAO_InputCDR (void);
00357 
00358   // = TAO specific methods.
00359 
00360   /// Accessor
00361   TAO_ORB_Core *orb_core (void) const;
00362 
00363   ACE_Message_Block::Message_Flags
00364     clr_mb_flags( ACE_Message_Block::Message_Flags less_flags );
00365 
00366   // = TAO specific methods.
00367   static void throw_stub_exception (int error_num);
00368   static void throw_skel_exception (int error_num);
00369 
00370 private:
00371   /// The ORB_Core, required to extract object references.
00372   TAO_ORB_Core* orb_core_;
00373 };
00374 
00375 TAO_END_VERSIONED_NAMESPACE_DECL
00376 
00377 #if defined(__ACE_INLINE__)
00378 # include "tao/CDR.inl"
00379 #else
00380 
00381 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
00382 
00383 // CDR output operators for CORBA types
00384 
00385 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00386                                       CORBA::Short x);
00387 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00388                                       CORBA::UShort x);
00389 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00390                                       CORBA::Long x);
00391 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00392                                       CORBA::ULong x);
00393 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00394                                       CORBA::LongLong x);
00395 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00396                                       CORBA::ULongLong x);
00397 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR& os,
00398                                       CORBA::LongDouble x);
00399 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00400                                       CORBA::Float x);
00401 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00402                                       CORBA::Double x);
00403 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00404                                       const CORBA::Char* x);
00405 TAO_Export CORBA::Boolean operator<< (TAO_OutputCDR &os,
00406                                       const CORBA::WChar* x);
00407 
00408 // CDR input operators for CORBA types
00409 
00410 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00411                                       CORBA::Short &x);
00412 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00413                                       CORBA::UShort &x);
00414 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00415                                       CORBA::Long &x);
00416 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00417                                       CORBA::ULong &x);
00418 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00419                                       CORBA::LongLong &x);
00420 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00421                                       CORBA::ULongLong &x);
00422 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00423                                       CORBA::LongDouble &x);
00424 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00425                                       CORBA::Float &x);
00426 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00427                                       CORBA::Double &x);
00428 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00429                                       CORBA::Char* &x);
00430 TAO_Export CORBA::Boolean operator>> (TAO_InputCDR &is,
00431                                       CORBA::WChar* &x);
00432 
00433 TAO_END_VERSIONED_NAMESPACE_DECL
00434 
00435 #endif /* __ACE_INLINE */
00436 
00437 #include /**/ "ace/post.h"
00438 #endif /* TAO_CDR_H */

Generated on Tue Feb 2 17:37:51 2010 for TAO by  doxygen 1.4.7