## NAME

ACE_IOStream - A template adapter for creating an iostream-like object using an ACE IPC Stream for the actual I/O. Iostreams use an underlying streambuf object for the IO interface. The iostream class and derivatives provide you with a host of convenient operators that access the streambuf.

## SYNOPSIS

    #include <ace/IOStream_T.h>

    template<class STREAM>
    class ACE_IOStream : public iostream, public STREAM
    {
      public:
        ACE_IOStream (
            STREAM &stream,
            u_int streambuf_size = ACE_STREAMBUF_SIZE
            );
        ACE_IOStream (u_int streambuf_size = ACE_STREAMBUF_SIZE);
        virtual ~ACE_IOStream (void);
        virtual int close (void);
        int eof (void) const;
        virtual ACE_IOStream<STREAM> &operator>> (ACE_IOStream_String &v);
        virtual ACE_IOStream<STREAM> &operator<< (ACE_IOStream_String &v);
        inline GETPUT_FUNC_SET (ACE_IOStream<STREAM>);
        inline virtual int ipfx (int noskip = 0);
        ACE_IOStream<STREAM> & operator>> (ACE_Time_Value *&tv);
      protected:
        ACE_Streambuf_T<STREAM> *streambuf_;
      private:
        inline ACE_UNIMPLEMENTED_FUNC (ssize_t send (...));
    };

## DESCRIPTION

We inherit all characteristics of iostream and your `STREAM` class. When you create a new class from this template, you can use it anywhere you would have used your original `STREAM` class.

To create an iostream for your favorite ACE IPC class (e.g., `ACE_SOCK_Stream`), feed that class to this template's `STREAM` parameter, e.g.,

typedef ACE_Svc_Handler`ACE_SOCK_iostream, ACE_INET_Addr, ACE_NULL_SYNCH` Service_Handler;

Because the operators in the iostream class are not virtual, you cannot easily provide overloads in your custom ACE_IOStream classes. To make these things work correctly, you need to overload ALL operators of the ACE_IOStream you create. I've attempted to do that here to make things easier for you but there are no guarantees.

In the iostream.cpp file is an example of why it is necessary to overload all of the get/put operators when you want to customize only one or two.

## Initialization and termination methods.

    ACE_IOStream (
        STREAM &stream,
        u_int streambuf_size = ACE_STREAMBUF_SIZE
        );

    ACE_IOStream (u_int streambuf_size = ACE_STREAMBUF_SIZE);

The default constructor. This will initiailze your STREAM and then setup the iostream baseclass to use a custom streambuf based on STREAM.

    virtual ~ACE_IOStream (void);

We have to get rid of the `streambuf_` ourselves since we gave it to the `iostream` base class;

    virtual int close (void);

The only ambituity in the multiple inheritance is the `close` function.

    int eof (void) const;

Returns 1 if we're at the end of the `STREAM`, i.e., if the connection has closed down or an error has occurred, else 0. Under the covers, eof() calls the streambuf's timeout() function which will reset the timeout flag. As as result, you should save the return of eof() and check it instead of calling eof() successively.

    virtual ACE_IOStream<STREAM> &operator>> (ACE_IOStream_String &v);

A simple string operator. The base `iostream` has them for char* but that isn't always the best thing for a `String`. If we don't provide our own here, we may not get what we want.

    virtual ACE_IOStream<STREAM> &operator<< (ACE_IOStream_String &v);

The converse of the `String::put` operator.

## Using the macros to provide get/set operators.

    inline GETPUT_FUNC_SET (ACE_IOStream<STREAM>);

    inline virtual int ipfx (int noskip = 0);

    ACE_IOStream<STREAM> & operator>> (ACE_Time_Value *&tv);

Allow the programmer to provide a timeout for read operations. Give it a pointer to NULL to block forever.

## Private methods.

We move these into the private section so that they cannot be used by the application programmer. This is necessary because streambuf_ will be buffering IO on the STREAM object. If these functions were used in your program, there is a danger of getting the datastream out of sync.

    inline ACE_UNIMPLEMENTED_FUNC (ssize_t send (...));

## AUTHOR

James CE Johnson `jcej@lads.com` and Jim Crossley `jim@lads.com`

## NOTE

This file should not be #included directly by application code. Instead, it should #include "ace/IOStream.h". That's because we only put some conditional compilations in that file.

## LIBRARY

ace