#ifndef _aplmt_fd_devices_fdnullapi_h_
#define _aplmt_fd_devices_fdnullapi_h_
/*----------------------------------------------------------------------------
** SUMMARY: APLMT File Descriptor: Null Device Interface (FDNULL)
**
** DESCRIPTION:
**  This file provides an interface for creating a file descritpor to 
**  a null device.  Typically, a null device is most useful for redirecting
**  output to the proverbial bitbucket.
**
**  BLOCKING:
**  ---------
**  None of the FD API methods will block on the IO operation since there is 
**  no underlying IO. However, Aplmt_openNullDevice() may block since it has
**  to update the internal FD table that is protected by a mutex.
**
**
** CONFIGURATION 
** -------------
**  COMPILE:     none.
**
**  APPLICATION: none.
**
**  PLATFORM:    none.
**
**
**  NOTES:
**  1. Unless explicitly stated otherwise, NONE of the following methods may be 
**     called from interrupt service routines.
**  2. Unless explicitly stated otherwise, NONE of the following methods may be 
**     called before the platform's kernel is running.
**  3. Unless explicitly stated otherwise, all of the following methods ARE 
**     thread-safe.
**  4. For efficency/optimization some methods are 'inlined'.  The inlining
**     is done by using the preprocessor/macros.  The application should
**     treat all methods as function calls and not rely on the fact they may
**     be currently defined as macros.
----------------------------------------------------------------------------*/

#include "aplmt/fd/fdapi.h"     /* For FD type */


#ifdef __cplusplus
extern "C" {
#endif

/*-------------- INLINE IMPLEMENTATION -------------------------------------*/
#include "aplmt/fd/devices/fdnull.h"        /* For: inline implementation */


/*-------------- PUBLIC/PUBLISHED API --------------------------------------*/
/** Creates a file descriptor to the "Null" Device. On success, the method 
    returns a file descriptor (>=0). If an error occurs, then an error code 
    (value <0) is returned.  The following table details the semantics of the 
    Null device with respect to the individual FD methods. <pre>

    Method                  Details
    --------------------    -------------------------------------------------
    Aplmt_close()           Always succeeds.
    Aplmt_read()            Always succeeds.  Returns 0 bytes copied (no 
                            copy is performed).
    Aplmt_write()           Always succeeds.   Returns 'count' as the number 
                            of bytes written (no copy is performed).
    Aplmt_available()       Always succeeds and returns 0.
    Aplmt_flush()           Always succeeds.
    Aplmt_getPos()          Always succeeds and sets 'curpos' to 0.
    Aplmt_setPos()          Succeeds if 'offset' equals zero, else fails and
                            returns APLMT_ERR_FD_EXCEED_EOF.
    Aplmt_geteof()          Always succeeds and sets 'eofOffset' to 0.
    All other methods       Fail and return APLMT_ERR_FD_INVALID_DESCRIPTOR.

    Prototype:
        AplmtFD Aplmt_openNullDevice( void );
</pre>*/
#define Aplmt_openNullDevice                _Aplmt_openNullDevice


#ifdef __cplusplus
}
#endif
/*--------------------------------------------------------------------------*/
#endif  /* end _aplmt_fd_devices_fdnullapi_h_ */