#ifndef AEERANDOMSOURCE_H
#define AEERANDOMSOURCE_H
/*======================================================
FILE: AEERandomSource.h

SERVICES: RandomSource random number generator

DESCRIPTION: This file provides the documentation for 
   BREW's FIPS186 compliant random number generator.
   Note, RandomSource exists only as a class and reuses
   the ISource interface.

CLASS IDs:	AEECLSID_RANDOM

        Copyright © 1999-2004 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
=====================================================*/

// AEECLSID_RANDOM defined in AEEClassIDs.h
#include "AEEClassIDs.h"

/*===========================================================================
   CLASS DOCUMENTATION
=============================================================================

AEECLSID_RANDOM

Description:
   This class provides a source of cryptographic quality random data from a 
FIPS186 compliant random number generator.

   This class uses real random data from an internal buffer when available 
as well as semi-random data collected during certain events in BREW.  The 
random bytes are generated using a FIPS186 compliant method.  Developers 
should use this interface to generate random data for cryptographic 
purposes.

   This class shares the ISource interface and is used like any other 
ISource object.  In particular, the ISOURCE_Read() function is 
used to fill a buffer with random bytes.

   Unlike a standard ISource object, the call to ISOURCE_Read() will never
block with an ISOURCE_WAIT or fail with an ISOURCE_END result.  It will
always return the requested number of bytes.  While ISOURCE_Readable() is
implemented for completeness, using it isn't required.  That is, a
RandomSource object can be used synchronously.

   Note that while a RandomSouce object can be used to generated a virtually 
unlimited amount of random data, care should be taken.  This interface 
relies on an internal buffer of pure random data which may be filled only a 
few times a second.  While ISOURCE_Read() will continue to return random 
bytes, the quality of the bytes will decrease over time until fresh 
random data can be pulled in from this buffer.  In general, ISOURCE_Read() 
will return the highest quality possible random bytes if it's not called 
more than a few times a second.

   Also note that some devices may not support an internal buffer of pure 
random data at all.  In those cases, RandomSource will continue to produce 
reasonable random data generated from events in BREW, but it will be of lower 
quality perhaps unsuited for cryptographic uses.

Default Interface:
   ISource

Other Supported Interfaces:
   None

=============================================================================*/

#endif AEERANDOMSOURCE_H