--- name: "ACE_InputCDR" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_InputCDR" --- # ACE\_InputCDR(3) A CDR stream for reading, i.e. for demarshalling. ## NAME ACE\_InputCDR - A CDR stream for reading, i.e. for demarshalling. ## SYNOPSIS ``` #include class ACE_InputCDR { public: friend class ACE_Char_Codeset_Translator; friend class ACE_WChar_Codeset_Translator; ACE_InputCDR ( const char *buf, size_t bufsiz, int byte_order = ACE_CDR_BYTE_ORDER ); ACE_InputCDR (size_t bufsiz, int byte_order = ACE_CDR_BYTE_ORDER); ACE_InputCDR ( const ACE_Message_Block *data, int byte_order = ACE_CDR_BYTE_ORDER ); ACE_InputCDR ( ACE_Data_Block *data, int byte_order = ACE_CDR_BYTE_ORDER ); ACE_InputCDR (const ACE_InputCDR& rhs); ACE_InputCDR& operator= (const ACE_InputCDR& rhs); ACE_InputCDR ( const ACE_InputCDR& rhs, size_t size, ACE_CDR::Long offset ); ACE_InputCDR (const ACE_InputCDR& rhs, size_t size); ACE_InputCDR ( const ACE_OutputCDR& rhs, ACE_Allocator* buffer_allocator = 0, ACE_Allocator* data_block_allocator = 0 ); struct ACE_Export Transfer_Contents { public: Transfer_Contents (ACE_InputCDR &rhs); ACE_InputCDR &rhs_; }; ``` ACE\_InputCDR (Transfer\_Contents rhs); ~ACE\_InputCDR (void); ACE\_CDR::Boolean read\_boolean (ACE\_CDR::Boolean& x); ACE\_CDR::Boolean read\_char (ACE\_CDR::Char &x); ACE\_CDR::Boolean read\_wchar (ACE\_CDR::WChar& x); ACE\_CDR::Boolean read\_octet (ACE\_CDR::Octet& x); ACE\_CDR::Boolean read\_short (ACE\_CDR::Short &x); ACE\_CDR::Boolean read\_ushort (ACE\_CDR::UShort &x); ACE\_CDR::Boolean read\_long (ACE\_CDR::Long &x); ACE\_CDR::Boolean read\_ulong (ACE\_CDR::ULong &x); ACE\_CDR::Boolean read\_longlong (ACE\_CDR::LongLong& x); ACE\_CDR::Boolean read\_ulonglong (ACE\_CDR::ULongLong& x); ACE\_CDR::Boolean read\_float (ACE\_CDR::Float &x); ACE\_CDR::Boolean read\_double (ACE\_CDR::Double &x); ACE\_CDR::Boolean read\_longdouble (ACE\_CDR::LongDouble &x); ACE\_CDR::Boolean read\_string (ACE\_CDR::Char \*&x); ACE\_CDR::Boolean read\_string (ACE\_CString &x); ACE\_CDR::Boolean read\_wstring (ACE\_CDR::WChar\*& x); ACE\_CDR::Boolean read\_boolean\_array (\ ACE\_CDR::Boolean\* x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_char\_array (\ ACE\_CDR::Char \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_wchar\_array (\ ACE\_CDR::WChar\* x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_octet\_array (\ ACE\_CDR::Octet\* x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_short\_array (\ ACE\_CDR::Short \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_ushort\_array (\ ACE\_CDR::UShort \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_long\_array (\ ACE\_CDR::Long \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_ulong\_array (\ ACE\_CDR::ULong \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_longlong\_array (\ ACE\_CDR::LongLong\* x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_ulonglong\_array (\ ACE\_CDR::ULongLong\* x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_float\_array (\ ACE\_CDR::Float \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_double\_array (\ ACE\_CDR::Double \*x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean read\_longdouble\_array (\ ACE\_CDR::LongDouble\* x,\ ACE\_CDR::ULong length\ ); ACE\_CDR::Boolean skip\_boolean (void); ACE\_CDR::Boolean skip\_char (void); ACE\_CDR::Boolean skip\_wchar (void); ACE\_CDR::Boolean skip\_octet (void); ACE\_CDR::Boolean skip\_short (void); ACE\_CDR::Boolean skip\_ushort (void); ACE\_CDR::Boolean skip\_long (void); ACE\_CDR::Boolean skip\_ulong (void); ACE\_CDR::Boolean skip\_longlong (void); ACE\_CDR::Boolean skip\_ulonglong (void); ACE\_CDR::Boolean skip\_float (void); ACE\_CDR::Boolean skip\_double (void); ACE\_CDR::Boolean skip\_longdouble (void); ACE\_CDR::Boolean skip\_wstring (void); ACE\_CDR::Boolean skip\_string (void); ACE\_CDR::Boolean skip\_bytes (size\_t n); int good\_bit (void) const; const ACE\_Message\_Block\* start (void) const; int grow (size\_t newsize); void reset\_byte\_order (int byte\_order); void reset (const ACE\_Message\_Block \*data, int byte\_order); ACE\_Message\_Block \*steal\_contents (void); void steal\_from (ACE\_InputCDR &cdr); void reset\_contents (void); char\* rd\_ptr (void); size\_t length (void) const; int align\_read\_ptr (size\_t alignment); int do\_byte\_swap (void) const; int byte\_order (void) const; ACE\_Char\_Codeset\_Translator \*char\_translator (void) const; ACE\_WChar\_Codeset\_Translator \*wchar\_translator (void) const;\ protected: ACE\_Message\_Block start\_; int do\_byte\_swap\_; int good\_bit\_; ACE\_Char\_Codeset\_Translator \*char\_translator\_; ACE\_WChar\_Codeset\_Translator \*wchar\_translator\_;\ private: ACE\_CDR::Boolean read\_1 (ACE\_CDR::Octet \*x); ACE\_CDR::Boolean read\_2 (ACE\_CDR::UShort \*x); ACE\_CDR::Boolean read\_4 (ACE\_CDR::ULong \*x); ACE\_CDR::Boolean read\_8 (ACE\_CDR::ULongLong \*x); ACE\_CDR::Boolean read\_16 (ACE\_CDR::LongDouble \*x); ACE\_CDR::Boolean read\_array (\ void\* x,\ size\_t size,\ size\_t align,\ ACE\_CDR::ULong length\ ); void rd\_ptr (size\_t offset); char\* end (void); int adjust (size\_t size, char \*&buf); int adjust (size\_t size, size\_t align, char \*&buf); }; ## DESCRIPTION ACE Common Data Representation (CDR) marshaling and demarshaling classes. This implementation was inspired in the CDR class in SunSoft's IIOP engine, but has a completely different implementation and a different interface too. The current implementation assumes that the host has 1-byte, 2-byte and 4-byte integral types, and that it has single precision and double precision IEEE floats. Those assumptions are pretty good these days, with Crays beign the only known exception. ## Special types. These extract octets, chars, booleans, and bounded strings ## We have one method per basic IDL type.... They return 0 on failure and 1 on success. ``` ACE_CDR::Boolean read_boolean (ACE_CDR::Boolean& x); ``` ``` ACE_CDR::Boolean read_char (ACE_CDR::Char &x); ``` ``` ACE_CDR::Boolean read_wchar (ACE_CDR::WChar& x); ``` ``` ACE_CDR::Boolean read_octet (ACE_CDR::Octet& x); ``` ``` ACE_CDR::Boolean read_short (ACE_CDR::Short &x); ``` ``` ACE_CDR::Boolean read_ushort (ACE_CDR::UShort &x); ``` ``` ACE_CDR::Boolean read_long (ACE_CDR::Long &x); ``` ``` ACE_CDR::Boolean read_ulong (ACE_CDR::ULong &x); ``` ``` ACE_CDR::Boolean read_longlong (ACE_CDR::LongLong& x); ``` ``` ACE_CDR::Boolean read_ulonglong (ACE_CDR::ULongLong& x); ``` ``` ACE_CDR::Boolean read_float (ACE_CDR::Float &x); ``` ``` ACE_CDR::Boolean read_double (ACE_CDR::Double &x); ``` ``` ACE_CDR::Boolean read_longdouble (ACE_CDR::LongDouble &x); ``` ``` ACE_CDR::Boolean read_string (ACE_CDR::Char *&x); ``` ``` ACE_CDR::Boolean read_string (ACE_CString &x); ``` ``` ACE_CDR::Boolean read_wstring (ACE_CDR::WChar*& x); ``` ## One method for each basic type... The buffer x must be large enough to contain length elements. They return -1 on failure and 0 on success. ``` ACE_CDR::Boolean read_boolean_array ( ACE_CDR::Boolean* x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_char_array ( ACE_CDR::Char *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_wchar_array ( ACE_CDR::WChar* x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_octet_array ( ACE_CDR::Octet* x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_short_array ( ACE_CDR::Short *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_ushort_array ( ACE_CDR::UShort *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_long_array ( ACE_CDR::Long *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_ulong_array ( ACE_CDR::ULong *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_longlong_array ( ACE_CDR::LongLong* x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_ulonglong_array ( ACE_CDR::ULongLong* x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_float_array ( ACE_CDR::Float *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_double_array ( ACE_CDR::Double *x, ACE_CDR::ULong length ); ``` ``` ACE_CDR::Boolean read_longdouble_array ( ACE_CDR::LongDouble* x, ACE_CDR::ULong length ); ``` ## The following functions are useful to read the contents of the CDR stream from a socket or file. ``` int grow (size_t newsize); ``` Grow the internal buffer, reset rd\_ptr to the first byte in the new buffer that is properly aligned, and set wr\_ptr to rd\_ptr + newsize ``` void reset_byte_order (int byte_order); ``` After reading and partially parsing the contents the user can detect a change in the byte order, this method will let him change it. ``` void reset (const ACE_Message_Block *data, int byte_order); ``` Re-initialize the CDR stream, copying the contents of the chain of message\_blocks starting from data. ``` ACE_Message_Block *steal_contents (void); ``` Steal the contents from the currect CDR. ``` void steal_from (ACE_InputCDR &cdr); ``` Steal the contents of cdr and make a shallow copy into this stream. ``` void reset_contents (void); ``` Re-initialize the CDR stream, forgetting about the old contents of the stream and allocating a new buffer (from the allocators). ``` char* rd_ptr (void); ``` Returns the current position for the rd\_ptr.... ``` size_t length (void) const; ``` Return how many bytes are left in the stream. ``` int align_read_ptr (size_t alignment); ``` Utility function to allow the user more flexibility. Skips up to the nearest alignment-byte boundary. Argument MUST be a power of 2. Returns 0 on success and -1 on failure. ``` int do_byte_swap (void) const; ``` If non-zero then this stream is writing in non-native byte order, this is only meaningful if ACE\_ENABLE\_SWAP\_ON\_WRITE is defined. ``` int byte_order (void) const; ``` If do\_byte\_swap returns 1, this returns ACE\_CDR\_BYTE\_ORDER else it returns ~ACE\_CDR\_BYTE\_ORDER. ``` ACE_Char_Codeset_Translator *char_translator (void) const; ``` ``` ACE_WChar_Codeset_Translator *wchar_translator (void) const; ``` Access the codeset translators. They can be nil! ## AUTHORS Aniruddha Gokhale gokhale@cs.wustl.edu and Carlos O'Ryan coryan@cs.wustl.edu for the original implementation in TAO. ACE version by Jeff Parsons parsons@cs.wustl.edu and Istvan Buki istvan.buki@euronet.be. Codeset translation by Jim Rogers (jrogers@viasoft.com) and Carlos O'Ryan coryan@cs.wustl.edu ## LIBRARY ace