// **********************************************************************
//
// Copyright (c) 2002
// IONA Technologies, Inc.
// Waltham, MA, USA
//
// All Rights Reserved
//
// **********************************************************************

#ifndef OCI_BUFFER_IDL
#define OCI_BUFFER_IDL

#pragma prefix "ooc.com"

module OCI
{

/**
 *
 * An interface for a buffer. A buffer can be viewed as an object
 * holding an array of octets and a position counter, which determines
 * how many octets have already been sent or received.
 *
 * The IDL interface definition for Buffer is incomplete and must be
 * extended by the specific language mappings. For example, the C++
 * mapping defines the following additional functions:
 *
 * <ul><li><code>Octet* data()</code>: Returns a C++
 * pointer to the first element of the array of octets, which
 * represents the buffer's contents.</li>
 *
 * <li><code>Octet* rest()</code>: Similar to <code>data()</code>, this
 * operation returns a C++ pointer, but to the n-th element of the
 * array of octets with n being the value of the position
 * counter.</li></ul>
 *
 **/

local interface Buffer
{
    /** The buffer length. */
    readonly attribute unsigned long length;

    /**
     *
     * The position counter. Note that the buffer's length and the
     * position counter don't depend on each other. There are no
     * restrictions on the values permitted for the counter. This
     * implies that it's even legal to set the counter to values
     * beyond the buffer's length.
     *
     **/

    attribute unsigned long pos;

    /**
     *
     * Increment the position counter.
     *
     * @param delta The value to add to the position counter.
     *
     **/

    void advance(in unsigned long delta);

    /**
     *
     * Returns the rest length of the buffer. The rest length is the
     * length minus the position counter's value. If the value of the
     * position counter exceeds the buffer's length, the return value
     * is undefined.
     *
     * @return The rest length.
     *
     **/

    unsigned long rest_length();

    /**
     *
     * Checks if the buffer is full. The buffer is considered full
     * if its length is equal to the position counter's value.
     *
     * @return <code>TRUE</code> if the buffer is
     * full, <code>FALSE</code> otherwise.
     *
     **/

    boolean is_full();
};

/** Alias for a sequence of buffers. */
typedef sequence< Buffer > BufferSeq;

}; // End module OCI

#endif
