diff options
Diffstat (limited to 'cpp/include/Ice/InputStream.h')
| -rw-r--r-- | cpp/include/Ice/InputStream.h | 747 |
1 files changed, 636 insertions, 111 deletions
diff --git a/cpp/include/Ice/InputStream.h b/cpp/include/Ice/InputStream.h index b2cba30b20e..021b12ac58b 100644 --- a/cpp/include/Ice/InputStream.h +++ b/cpp/include/Ice/InputStream.h @@ -29,6 +29,7 @@ namespace Ice class UserException; +/// \cond INTERNAL template<typename T> inline void patchHandle(void* addr, const ValuePtr& v) { @@ -44,49 +45,139 @@ patchHandle(void* addr, const ValuePtr& v) _icePatchObjectPtr(*p, v); // Generated _icePatchObjectPtr function, necessary for forward declarations. #endif } +/// \endcond +/** + * Interface for input streams used to extract Slice types from a sequence of bytes. + * \headerfile Ice/Ice.h + */ class ICE_API InputStream : public IceInternal::Buffer { public: typedef size_t size_type; + + /** + * Signature for a patch function, used to receive an unmarshaled value. + * @param addr The target address. + * @param v The unmarshaled value. + */ typedef void (*PatchFunc)(void*, const ValuePtr&); - // - // These constructors use the latest encoding version. Without a communicator, the stream - // will not be able to unmarshal a proxy. For other unmarshaling tasks, you can provide - // Helpers for objects that are normally provided by a communicator. - // + /** + * Constructs a stream using the latest encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + */ InputStream(); - InputStream(const std::vector<Byte>&); - InputStream(const std::pair<const Byte*, const Byte*>&); - InputStream(IceInternal::Buffer&, bool = false); - - // - // These constructors use the communicator's default encoding version. - // - InputStream(const CommunicatorPtr&); - InputStream(const CommunicatorPtr&, const std::vector<Byte>&); - InputStream(const CommunicatorPtr&, const std::pair<const Byte*, const Byte*>&); - InputStream(const CommunicatorPtr&, IceInternal::Buffer&, bool = false); - // - // These constructors use the given encoding version. Without a communicator, the stream - // will not be able to unmarshal a proxy. For other unmarshaling tasks, you can provide - // Helpers for objects that are normally provided by a communicator. - // - InputStream(const EncodingVersion&); - InputStream(const EncodingVersion&, const std::vector<Byte>&); - InputStream(const EncodingVersion&, const std::pair<const Byte*, const Byte*>&); + /** + * Constructs a stream using the latest encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param bytes The encoded data. + */ + InputStream(const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the latest encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param bytes The encoded data. + */ + InputStream(const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL + InputStream(IceInternal::Buffer&, bool = false); + /// \endcond + + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + */ + InputStream(const CommunicatorPtr& communicator); + + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the communicator's default encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL + InputStream(const CommunicatorPtr& communicator, IceInternal::Buffer&, bool = false); + /// \endcond + + /** + * Constructs a stream using the given encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param version The encoding version used to encode the data to be unmarshaled. + */ + InputStream(const EncodingVersion& version); + + /** + * Constructs a stream using the given encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const EncodingVersion& version, const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the given encoding version but without a communicator. + * This stream will not be able to unmarshal a proxy. For other unmarshaling tasks, + * you can provide Helpers for objects that are normally provided by a communicator. + * You can supply a communicator later by calling initialize(). + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const EncodingVersion& version, const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL InputStream(const EncodingVersion&, IceInternal::Buffer&, bool = false); - - // - // These constructors use the given communicator and encoding version. - // - InputStream(const CommunicatorPtr&, const EncodingVersion&); - InputStream(const CommunicatorPtr&, const EncodingVersion&, const std::vector<Byte>&); - InputStream(const CommunicatorPtr&, const EncodingVersion&, const std::pair<const Byte*, const Byte*>&); + /// \endcond + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + */ + InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version); + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version, const std::vector<Byte>& bytes); + + /** + * Constructs a stream using the given communicator and encoding version. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + * @param bytes The encoded data. + */ + InputStream(const CommunicatorPtr& communicator, const EncodingVersion& version, + const std::pair<const Byte*, const Byte*>& bytes); + + /// \cond INTERNAL InputStream(const CommunicatorPtr&, const EncodingVersion&, IceInternal::Buffer&, bool = false); + /// \endcond ~InputStream() { @@ -106,75 +197,184 @@ public: #endif } - // - // Use initialize() if you originally constructed the stream without a communicator. - // - void initialize(const CommunicatorPtr&); - void initialize(const CommunicatorPtr&, const EncodingVersion&); - + /** + * Initializes the stream to use the communicator's default encoding version. + * Use initialize() if you originally constructed the stream without a communicator. + * @param communicator The communicator to use for unmarshaling tasks. + */ + void initialize(const CommunicatorPtr& communicator); + + /** + * Initializes the stream to use the given communicator and encoding version. + * Use initialize() if you originally constructed the stream without a communicator. + * @param communicator The communicator to use for unmarshaling tasks. + * @param version The encoding version used to encode the data to be unmarshaled. + */ + void initialize(const CommunicatorPtr& communicator, const EncodingVersion& version); + + /** + * Releases any data retained by encapsulations. + */ void clear(); + /// \cond INTERNAL // // Must return Instance*, because we don't hold an InstancePtr for // optimization reasons (see comments below). // IceInternal::Instance* instance() const { return _instance; } // Inlined for performance reasons. - - void setValueFactoryManager(const ValueFactoryManagerPtr&); - - void setLogger(const LoggerPtr&); - + /// \endcond + + /** + * Sets the value factory manager to use when unmarshaling value instances. If the stream + * was initialized with a communicator, the communicator's value factory manager will + * be used by default. + * + * @param vfm The value factory manager. + */ + void setValueFactoryManager(const ValueFactoryManagerPtr& vfm); + + /** + * Sets the logger to use when logging trace messages. If the stream + * was initialized with a communicator, the communicator's logger will + * be used by default. + * + * @param logger The logger to use for logging trace messages. + */ + void setLogger(const LoggerPtr& logger); + + /** + * Sets the compact ID resolver to use when unmarshaling value and exception + * instances. If the stream was initialized with a communicator, the communicator's + * resolver will be used by default. + * + * @param r The compact ID resolver. + */ #ifdef ICE_CPP11_MAPPING - void setCompactIdResolver(std::function<std::string(int)>); + void setCompactIdResolver(std::function<std::string(int)> r); #else - void setCompactIdResolver(const CompactIdResolverPtr&); + void setCompactIdResolver(const CompactIdResolverPtr& r); #endif #ifndef ICE_CPP11_MAPPING - void setCollectObjects(bool); + /** + * Indicates whether to mark instances of Slice classes as collectable. If the stream is + * initialized with a communicator, this setting defaults to the value of the + * Ice.CollectObjects property, otherwise the setting defaults to false. + * @param b True to mark instances as collectable, false otherwise. + */ + void setCollectObjects(bool b); #endif - void setSliceValues(bool); - - void setTraceSlicing(bool); - - void setClassGraphDepthMax(size_t); - + /** + * Indicates whether to slice instances of Slice classes to a known Slice type when a more + * derived type is unknown. An instance is "sliced" when no static information is available + * for a Slice type ID and no factory can be found for that type, resulting in the creation + * of an instance of a less-derived type. If slicing is disabled in this situation, the + * stream raises the exception NoValueFactoryException. The default behavior is to allow slicing. + * @param b True to enable slicing, false otherwise. + */ + void setSliceValues(bool b); + + /** + * Indicates whether to log messages when instances of Slice classes are sliced. If the stream + * is initialized with a communicator, this setting defaults to the value of the Ice.Trace.Slicing + * property, otherwise the setting defaults to false. + * @param b True to enable logging, false otherwise. + */ + void setTraceSlicing(bool b); + + /** + * Sets an upper limit on the depth of a class graph. If this limit is exceeded during + * unmarshaling, the stream raises MarshalException. + * @param n The maximum depth. + */ + void setClassGraphDepthMax(size_t n); + + /** + * Obtains the closure data associated with this stream. + * @return The data as a void pointer. + */ void* getClosure() const; - void* setClosure(void*); - - void swap(InputStream&); + /** + * Associates closure data with this stream. + * @param p The data as a void pointer. + * @return The previous closure data, or nil. + */ + void* setClosure(void* p); + + /** + * Swaps the contents of one stream with another. + * + * @param other The other stream. + */ + void swap(InputStream& other); + + /// \cond INTERNAL void resetEncapsulation(); + /// \endcond + /** + * Resizes the stream to a new size. + * + * @param sz The new size. + */ void resize(Container::size_type sz) { b.resize(sz); i = b.end(); } + /** + * Marks the start of a class instance. + */ void startValue() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->startInstance(ValueSlice); } + + /** + * Marks the end of a class instance. + * + * @param preserve Pass true and the stream will preserve the unknown slices of the instance, or false + * to discard the unknown slices. + * @return An object that encapsulates the unknown slice data. + */ SlicedDataPtr endValue(bool preserve) { assert(_currentEncaps && _currentEncaps->decoder); return _currentEncaps->decoder->endInstance(preserve); } + /** + * Marks the start of a user exception. + */ void startException() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->startInstance(ExceptionSlice); } + + /** + * Marks the end of a user exception. + * + * @param preserve Pass true and the stream will preserve the unknown slices of the exception, or false + * to discard the unknown slices. + * @return An object that encapsulates the unknown slice data. + */ SlicedDataPtr endException(bool preserve) { assert(_currentEncaps && _currentEncaps->decoder); return _currentEncaps->decoder->endInstance(preserve); } + /** + * Reads the start of an encapsulation. + * + * @return The encoding version used by the encapsulation. + */ const EncodingVersion& startEncapsulation() { Encaps* oldEncaps = _currentEncaps; @@ -214,6 +414,9 @@ public: return _currentEncaps->encoding; } + /** + * Ends the current encapsulation. + */ void endEncapsulation() { assert(_currentEncaps); @@ -254,6 +457,11 @@ public: } } + /** + * Skips an empty encapsulation. + * + * @return The encapsulation's encoding version. + */ EncodingVersion skipEmptyEncapsulation() { Ice::Int sz; @@ -286,6 +494,13 @@ public: return encoding; } + /** + * Returns a blob of bytes representing an encapsulation. + * + * @param v A pointer into the internal marshaling buffer representing the start of the encoded encapsulation. + * @param sz The number of bytes in the encapsulation. + * @return encoding The encapsulation's encoding version. + */ EncodingVersion readEncapsulation(const Byte*& v, Int& sz) { EncodingVersion encoding; @@ -305,32 +520,71 @@ public: return encoding; } + /** + * Determines the current encoding version. + * + * @return The encoding version. + */ const EncodingVersion& getEncoding() const { return _currentEncaps ? _currentEncaps->encoding : _encoding; } + /** + * Determines the size of the current encapsulation, excluding the encapsulation header. + * + * @return The size of the encapsulated data. + */ Int getEncapsulationSize(); + + /** + * Skips over an encapsulation. + * + * @return The encoding version of the skipped encapsulation. + */ EncodingVersion skipEncapsulation(); + /** + * Reads the start of a value or exception slice. + * + * @return The Slice type ID for this slice. + */ std::string startSlice() { assert(_currentEncaps && _currentEncaps->decoder); return _currentEncaps->decoder->startSlice(); } + + /** + * Indicates that the end of a value or exception slice has been reached. + */ void endSlice() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->endSlice(); } + + /** + * Skips over a value or exception slice. + */ void skipSlice() { assert(_currentEncaps && _currentEncaps->decoder); _currentEncaps->decoder->skipSlice(); } + /** + * Indicates that unmarshaling is complete, except for any class instances. The application must call this method + * only if the stream actually contains class instances. Calling readPendingValues triggers the + * patch callbacks to inform the application that unmarshaling of an instance is complete. + */ void readPendingValues(); + /** + * Extracts a size from the stream. + * + * @return The extracted size. + */ Int readSize() // Inlined for performance reasons. { Byte byte; @@ -352,10 +606,28 @@ public: } } - Int readAndCheckSeqSize(int); - - void readBlob(std::vector<Byte>&, Int); - + /** + * Reads and validates a sequence size. + * + * @param minSize The minimum size required by the sequence type. + * @return The extracted size. + */ + Int readAndCheckSeqSize(int minSize); + + /** + * Reads a blob of bytes from the stream. + * + * @param bytes The vector to hold a copy of the bytes from the marshaling buffer. + * @param sz The number of bytes to read. + */ + void readBlob(std::vector<Byte>& bytes, Int sz); + + /** + * Reads a blob of bytes from the stream. + * + * @param v A pointer into the internal marshaling buffer representing the start of the blob. + * @param sz The number of bytes to read. + */ void readBlob(const Byte*& v, Container::size_type sz) { if(sz > 0) @@ -373,11 +645,20 @@ public: } } + /** + * Reads a data value from the stream. + * @param v Holds the extracted data. + */ template<typename T> void read(T& v) { StreamHelper<T, StreamableTraits<T>::helper>::read(this, v); } + /** + * Reads an optional data value from the stream. + * @param tag The tag ID. + * @param v Holds the extracted data (if any). + */ template<typename T> void read(Int tag, IceUtil::Optional<T>& v) { if(readOptional(tag, StreamOptionalHelper<T, @@ -401,6 +682,10 @@ public: #ifdef ICE_CPP11_MAPPING + /** + * Extracts a sequence of data values from the stream. + * @param v A pair of pointers representing the beginning and end of the sequence elements. + */ template<typename T> void read(std::pair<const T*, const T*>& v) { auto holder = new std::vector<T>; @@ -418,23 +703,35 @@ public: } } + /** + * Reads a list of mandatory data values. + */ template<typename T> void readAll(T& v) { read(v); } + /** + * Reads a list of mandatory data values. + */ template<typename T, typename... Te> void readAll(T& v, Te&... ve) { read(v); readAll(ve...); } + /** + * Reads a list of optional data values. + */ template<typename T> void readAll(std::initializer_list<int> tags, IceUtil::Optional<T>& v) { read(*(tags.begin() + tags.size() - 1), v); } + /** + * Reads a list of optional data values. + */ template<typename T, typename... Te> void readAll(std::initializer_list<int> tags, IceUtil::Optional<T>& v, IceUtil::Optional<Te>&... ve) { @@ -445,7 +742,13 @@ public: #endif - // Read type and tag for optionals + /** + * Determine if an optional value is available for reading. + * + * @param tag The tag associated with the value. + * @param expectedFormat The optional format for the value. + * @return True if the value is present, false otherwise. + */ bool readOptional(Int tag, OptionalFormat expectedFormat) { assert(_currentEncaps); @@ -459,7 +762,10 @@ public: } } - // Byte + /** + * Reads a byte from the stream. + * @param v The extracted byte. + */ void read(Byte& v) { if(i >= b.end()) @@ -468,19 +774,38 @@ public: } v = *i++; } - void read(std::vector<Byte>&); - void read(std::pair<const Byte*, const Byte*>&); + + /** + * Reads a sequence of bytes from the stream. + * @param v A vector to hold a copy of the bytes. + */ + void read(std::vector<Byte>& v); + + /** + * Reads a sequence of bytes from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + */ + void read(std::pair<const Byte*, const Byte*>& v); #ifndef ICE_CPP11_MAPPING - // This method is useful for generic stream helpers - void read(std::pair<const Byte*, const Byte*>& p, ::IceUtil::ScopedArray<Byte>& result) + /** + * Reads a sequence of bytes from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Byte*, const Byte*>& v, ::IceUtil::ScopedArray<Byte>& arr) { - result.reset(); - read(p); + arr.reset(); + read(v); } #endif - // Bool + /** + * Reads a bool from the stream. + * @param v The extracted bool. + */ void read(bool& v) { if(i >= b.end()) @@ -489,24 +814,61 @@ public: } v = (0 != *i++); } - void read(std::vector<bool>&); + + /** + * Reads a sequence of boolean values from the stream. + * @param v A vector to hold a copy of the boolean values. + */ + void read(std::vector<bool>& v); #ifdef ICE_CPP11_MAPPING - void read(std::pair<const bool*, const bool*>&); + /** + * Reads a sequence of boolean values from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + */ + void read(std::pair<const bool*, const bool*>& v); #else - void read(std::pair<const bool*, const bool*>&, ::IceUtil::ScopedArray<bool>&); + /** + * Reads a sequence of boolean values from the stream. + * @param v A pair of pointers into the internal marshaling buffer representing the start and end of the + * sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const bool*, const bool*>& v, ::IceUtil::ScopedArray<bool>& arr); #endif - // Short - void read(Short&); - void read(std::vector<Short>&); + /** + * Reads a short from the stream. + * @param v The extracted short. + */ + void read(Short& v); + + /** + * Reads a sequence of shorts from the stream. + * @param v A vector to hold a copy of the short values. + */ + void read(std::vector<Short>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const short*, const short*>&); + /** + * Reads a sequence of boolean values from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const short*, const short*>& v); #else - void read(std::pair<const Short*, const Short*>&, ::IceUtil::ScopedArray<Short>&); + /** + * Reads a sequence of shorts from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Short*, const Short*>& v, ::IceUtil::ScopedArray<Short>& arr); #endif - // Int + /** + * Reads an int from the stream. + * @param v The extracted int. + */ void read(Int& v) // Inlined for performance reasons. { if(b.end() - i < static_cast<int>(sizeof(Int))) @@ -530,63 +892,175 @@ public: #endif } - void read(std::vector<Int>&); + /** + * Reads a sequence of ints from the stream. + * @param v A vector to hold a copy of the int values. + */ + void read(std::vector<Int>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const int*, const int*>&); + /** + * Reads a sequence of ints from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const int*, const int*>& v); #else - void read(std::pair<const Int*, const Int*>&, ::IceUtil::ScopedArray<Int>&); + /** + * Reads a sequence of ints from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Int*, const Int*>& v, ::IceUtil::ScopedArray<Int>& arr); #endif - // Long + /** + * Reads a long from the stream. + * @param v The extracted long. + */ + void read(Long& v); + + /** + * Reads a sequence of longs from the stream. + * @param v A vector to hold a copy of the long values. + */ + void read(std::vector<Long>& v); - void read(Long&); - void read(std::vector<Long>&); #ifdef ICE_CPP11_MAPPING - void read(std::pair<const long long*, const long long*>&); + /** + * Reads a sequence of longs from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const long long*, const long long*>& v); #else - void read(std::pair<const Long*, const Long*>&, ::IceUtil::ScopedArray<Long>&); + /** + * Reads a sequence of longs from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Long*, const Long*>& v, ::IceUtil::ScopedArray<Long>& arr); #endif - // Float - void read(Float&); - void read(std::vector<Float>&); + /** + * Reads a float from the stream. + * @param v The extracted float. + */ + void read(Float& v); + + /** + * Reads a sequence of floats from the stream. + * @param v A vector to hold a copy of the float values. + */ + void read(std::vector<Float>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const float*, const float*>&); + /** + * Reads a sequence of floats from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const float*, const float*>& v); #else - void read(std::pair<const Float*, const Float*>&, ::IceUtil::ScopedArray<Float>&); + /** + * Reads a sequence of floats from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Float*, const Float*>& v, ::IceUtil::ScopedArray<Float>& arr); #endif - // Double - void read(Double&); - void read(std::vector<Double>&); + /** + * Reads a double from the stream. + * @param v The extracted double. + */ + void read(Double& v); + + /** + * Reads a sequence of doubles from the stream. + * @param v A vector to hold a copy of the double values. + */ + void read(std::vector<Double>& v); + #ifdef ICE_CPP11_MAPPING - void read(std::pair<const double*, const double*>&); + /** + * Reads a sequence of doubles from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + */ + void read(std::pair<const double*, const double*>& v); #else - void read(std::pair<const Double*, const Double*>&, ::IceUtil::ScopedArray<Double>&); + /** + * Reads a sequence of doubles from the stream. + * @param v A pair of pointers representing the start and end of the sequence elements. + * @param arr A scoped array. + */ + void read(std::pair<const Double*, const Double*>& v, ::IceUtil::ScopedArray<Double>& arr); #endif - // String + /** + * Reads a string from the stream. + * @param v The extracted string. + * @param convert Determines whether the string is processed by the string converter, if one + * is installed. The default behavior is to convert strings. + */ void read(std::string& v, bool convert = true); #ifdef ICE_CPP11_MAPPING + /** + * Reads a string from the stream. + * @param vdata A pointer to the beginning of the string. + * @param vsize The number of bytes in the string. + * @param convert Determines whether the string is processed by the string converter, if one + * is installed. The default behavior is to convert strings. + */ void read(const char*& vdata, size_t& vsize, bool convert = true); #else // For custom strings, convert = false + /** + * Reads a string from the stream. String conversion is disabled. + * @param vdata A pointer to the beginning of the string. + * @param vsize The number of bytes in the string. + */ void read(const char*& vdata, size_t& vsize); // For custom strings, convert = true + /** + * Reads a string from the stream. String conversion is enabled. + * @param vdata A pointer to the beginning of the string. + * @param vsize The number of bytes in the string. + * @param holder Holds the string contents. + */ void read(const char*& vdata, size_t& vsize, std::string& holder); #endif - void read(std::vector<std::string>&, bool = true); - - void read(std::wstring&); - void read(std::vector<std::wstring>&); + /** + * Reads a sequence of strings from the stream. + * @param v The extracted string sequence. + * @param convert Determines whether strings are processed by the string converter, if one + * is installed. The default behavior is to convert the strings. + */ + void read(std::vector<std::string>& v, bool convert = true); + + /** + * Reads a wide string from the stream. + * @param v The extracted string. + */ + void read(std::wstring& v); + + /** + * Reads a sequence of wide strings from the stream. + * @param v The extracted sequence. + */ + void read(std::vector<std::wstring>& v); - // Proxy #ifdef ICE_CPP11_MAPPING + /** + * Reads a proxy from the stream. + * @return The proxy as the base ObjectPrx type. + */ std::shared_ptr<ObjectPrx> readProxy(); + /** + * Reads a typed proxy from the stream. + * @param v The proxy as a user-defined type. + */ template<typename T, typename ::std::enable_if<::std::is_base_of<ObjectPrx, T>::value>::type* = nullptr> void read(::std::shared_ptr<T>& v) { @@ -602,14 +1076,26 @@ public: } } #else - void read(ObjectPrx&); + /** + * Reads a proxy from the stream. + * @param v The proxy as the base ObjectPrx type. + */ + void read(ObjectPrx& v); + + /** + * Reads a typed proxy from the stream. + * @param v The proxy as a user-defined type. + */ template<typename T> void read(IceInternal::ProxyHandle<T>& v) { _readProxy(this, v); // Generated _readProxy method, necessary for forward declarations. } #endif - // Class + /** + * Reads a value (instance of a Slice class) from the stream. + * @param v The instance. + */ #ifdef ICE_CPP11_MAPPING // C++11 mapping template<typename T, typename ::std::enable_if<::std::is_base_of<Value, T>::value>::type* = nullptr> void read(::std::shared_ptr<T>& v) @@ -623,23 +1109,48 @@ public: } #endif + /** + * Reads a value (instance of a Slice class) from the stream. + * @param patchFunc The patch callback function. + * @param patchAddr Closure data passed to the callback. + */ void read(PatchFunc patchFunc, void* patchAddr) { initEncaps(); _currentEncaps->decoder->read(patchFunc, patchAddr); } - // Enum - Int readEnum(Int); - - // Exception - void throwException(ICE_IN(ICE_DELEGATE(UserExceptionFactory)) = ICE_NULLPTR); - - // Read/write/skip optionals - void skipOptional(OptionalFormat); + /** + * Reads an enumerator from the stream. + * @param maxValue The maximum enumerator value in the definition. + * @return The enumerator value. + */ + Int readEnum(Int maxValue); + + /** + * Extracts a user exception from the stream and throws it. + * @param factory If provided, this factory is given the first opportunity to instantiate + * the exception. If not provided, or if the factory does not throw an exception when invoked, + * the stream will attempt to instantiate the exception using static type information. + * @throws UserException The user exception that was unmarshaled. + */ + void throwException(ICE_IN(ICE_DELEGATE(UserExceptionFactory)) factory = ICE_NULLPTR); + + /** + * Skips one optional value with the given format. + * @param format The expected format of the optional, if present. + */ + void skipOptional(OptionalFormat format); + + /** + * Skips all remaining optional values. + */ void skipOptionals(); - // Skip bytes from the stream + /** + * Advances the current stream position by the given number of bytes. + * @param size The number of bytes to skip. + */ void skip(size_type size) { if(i + size > b.end()) @@ -648,6 +1159,10 @@ public: } i += size; } + + /** + * Reads a size at the current position and skips that number of bytes. + */ void skipSize() { Byte bt; @@ -658,22 +1173,32 @@ public: } } + /** + * Obtains the current position of the stream. + * @return The current position. + */ size_type pos() { return i - b.begin(); } + /** + * Sets a new position for the stream. + * @param p The new position. + */ void pos(size_type p) { i = b.begin() + p; } + /// \cond INTERNAL InputStream(IceInternal::Instance*, const EncodingVersion&); InputStream(IceInternal::Instance*, const EncodingVersion&, IceInternal::Buffer&, bool = false); void initialize(IceInternal::Instance*, const EncodingVersion&); bool readOptImpl(Int, OptionalFormat); + /// \endcond private: |