cbbqueue.h

著名的 helix realplayer 基于手机 symbian 系统的 播放器全套源代码

	*	In particular this method will remain valid even across changes
	*	of object size in subclasses.
	*	The client will only NEED to imlement an override if they need
	*	to perform additional processing besides the block move of
	*	bits.
	*
	*  RETURNS:
	*	Number of bytes read out of the queue.
	*/
	virtual UINT32 DeQueue( void *pOutBuffer, UINT32 ulItemCount )
	{
		HX_ASSERT( this );
		HX_ASSERT( IsQueueValid() );
		HX_ASSERT( pOutBuffer );

		return( Base_DeQueueBytes( pOutBuffer, ulItemCount * m_ulElementSize ) );
	}

   /*
	** UINT32 EnQueue( pInBuffer, ulItemCount )
	*
	*  PARAMETERS:
	*	pInBuffer		Pointer to bytes we want to enqueue.
	*	ulItemCount		Number of items we want to enqueue.
	*
	*  DESCRIPTION:
	*	One of our primary operations.
	*	The client can redefine this function, but it is NOT necessary
	*	as the default implementation will suffice for most cases.
	*	In particular this method will remain valid even across changes
	*	of object size in subclasses.
	*	The client will only NEED to imlement an override if they need
	*	to perform additional processing besides the block move of
	*	bits.
	*
	*  RETURNS:
	*	0			If there was not enough room to EnQueue() all the items 
	*				specified.
	*	Non-Zero 	To indicate that all items specified were enqueue'd.
	*
	*/
	virtual UINT32 EnQueue( void *pInBuffer, UINT32 ulItemCount )
	{
		HX_ASSERT( this );
		HX_ASSERT( IsQueueValid() );
		HX_ASSERT( pInBuffer );

		return( Base_EnQueueBytes( pInBuffer, ulItemCount * m_ulElementSize ) );
	}


	/*
	 * Grow the queue to twice its size or at least big enough to hold n more,
	 * whichever is greater.  Returns 1 for good, 0 for bad.
	 */
	int Grow(UINT32 ulItems);

	void SetMaxSize(UINT32 ulMax);


	


/*
 *	Protected primitives for accessing the buffer and it's 
 *	pointers directly.
 *	These methods are available to our subclasses, but NOT to our
 *	clients.
 */
protected:
   /*
	** UINT32 Base_GetBufferSize()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
    *	Returns the actual allocated size of the buffer.
	*
	*  RETURNS:
	*	Size of the allocated buffer.
	*/
	UINT32 Base_GetBufferSize() const
	{
		HX_ASSERT( this );

		return( m_ulSize );
	}

   /*
	** UINT16 Base_GetMaxBufferSize()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
	*	Returns the max size of the queue.
	*
	*  RETURNS:
	*	Returns the max size of the queue.
	*/
	UINT32 Base_GetMaxBufferSize() const
	{
		HX_ASSERT( this );

		return( m_ulMaxSize );
	}

   /*
	** UINT32 Base_GetUsedByteCount()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
	*	Returns the actual number of bytes we've enqueued.
	*
	*  RETURNS:
	*	Number of bytes in USE in the queue.
	*/
	UINT32 Base_GetUsedByteCount() const
	{
		LONG32		iItemCount;

		HX_ASSERT( this );
		HX_ASSERT( IsQueueValid() );    

		iItemCount = (LONG32)(m_pTail - m_pHead);

		//	If iItemCount < 0 then we need to add m_nSize
		iItemCount += (iItemCount < 0) ? Base_GetBufferSize() : 0;
		HX_ASSERT(iItemCount <= (LONG32)Base_GetBufferSize());
		return( (UINT32)iItemCount );
	}

   /*
	** UINT32 Base_GetAvailableBytes()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
	*	Returns the number of bytes we can enqueue w/o failing.
	*
	*  RETURNS:
	*	Returns the number of bytes we can enqueue w/o failing.
	*/
	UINT32 Base_GetAvailableBytes() const
	{
		HX_ASSERT( this );
		HX_ASSERT( IsQueueValid() );    

		return( Base_GetBufferSize() - Base_GetUsedByteCount() - 1 );
	}

   /*
	** UINT32 Base_GetMaxAvailableBytes()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
	*	Returns the number of bytes we can enqueue w/o failing AFTER
	*	the queue has been grown to its maximum capacity.
	*
	*  RETURNS:
	*	Returns the number of bytes we can enqueue w/o failing.
	*/
	UINT32 Base_GetMaxAvailableBytes() const
	{
		HX_ASSERT( this );
		HX_ASSERT( IsQueueValid() );    

		return( Base_GetMaxBufferSize() - Base_GetUsedByteCount() - 1 );
	}

   /*
	** UINT32 Base_EnQueueBytes( pInBuffer, ulByteCount )
	*
	*  PARAMETERS:
	*	pInBuffer		Pointer to bytes to enqueue.
	*	ulByteCount		Number of bytes to enqueue.
	*
	*  DESCRIPTION:
	*	Enqueue's a stream of bytes.
	*	(Puts bytes INTO the queue)
	*
	*  RETURNS:
	*	0 if there was insufficient room to enqueue nByteCount bytes.
	*	Number of bytes enqueued.
	*
	*/
	UINT32 Base_EnQueueBytes( void *pInBuffer, UINT32 ulByteCount );

   /*
	** UINT32 Base_DeQueueBytes( pOutBuffer, ulByteCount )
	*
	*  PARAMETERS:
	*	pOutBuffer		Pointer to buffer to receive bytes from queue.
	*	ulByteCount		Number of bytes to remove from queue.
	*
	*  DESCRIPTION:
	*	DeQueue's a stream of bytes.
	*	(Takes bytes OUT of the queue)
	*
	*  RETURNS:
	*	The number of bytes dequeued from the queue.
	*/
	UINT32 Base_DeQueueBytes( void *pOutBuffer, UINT32 ulByteCount );


/*
 *	Private Implementation data.  We don't share this stuff w/ our subclasses.
 *	this way we can enforce our public and protected interface.
 */
private:
	UCHAR	*m_pData;   // the actual buffer pointer.
	UCHAR	*m_pHead;	// points one byte before the next bytes to be
						//	dequeue'd() from the queue (if !Empty).
	UCHAR	*m_pTail;	// points at last byte of valid data in queue.
						//	actually one byte before the next byte to receive new queue'd data
	UCHAR	*m_pMax;	// pointer to one position beyond what we've allocated
						//	helps us limit check m_pHead & mpTail.

	UINT32		m_ulSize;	// # of bytes in alloacated buffer
	
	UINT32		m_ulElementSize;	//	For our subclasses it's the size of an element
						//	We'll make our buffer a multiple of this
	UINT32		m_ulMaxSize;		// if set, max size queue can grow to.

	enum
	{
		FILLER_BYTE = 0xCC
	};
								
   /*
	** void Base_SetEmpty()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
	*	Instantly empty the queue.
	*
	*  RETURNS:
	*
	*/
	void Base_SetEmpty()
	{
		HX_ASSERT( this );

		m_pTail = m_pHead = m_pMax - 1;
	}
	
   /*
	** PBYTE Base_Normalize( pBuffer )
	*
	*  PARAMETERS:
	*	pBuffer		Pointer to our buffer that we want to normalize.
	*
	*  DESCRIPTION:
	*	Used to keep buffer pointer elements (m_pHead & m_pTail) in range 
	*	of m_pData to m_pMax-1.
	*	Basically this method helps us implement the mod function except
	*	we work w/ pointers, and we don't actually divide.
	*
	*  RETURNS:
	*	Normalized pointer.
	*/
	UCHAR * Base_Normalize( UCHAR * pBuffer, UINT32 offset ) const
	{
		HX_ASSERT( this );
		HX_ASSERT( IsQueueValid() );
		HX_ASSERT( pBuffer );

		pBuffer += offset;
		while (pBuffer >= m_pMax)
		{
			pBuffer -= m_ulSize;
		}
		return( pBuffer );
	}

   /*
	** UINT32 Base_GranulatedSize( ulSize, ulGranularity )
	*
	*  PARAMETERS:
	*	ulSize			A "proposed" size for our buffer.
	*	ulGranularity	The multiplier (for subclasses this is the size
	*					of one of our elements).
	*
	*  DESCRIPTION:
	*	Performs calcs to ensure our size is a multiple of our granularity.
	*	This is done by rounding UP to the next even multiple of nGranularity
	*	that is >= nSize.
	*
	*  RETURNS:
	*	A rounded up quantity.
	*/
	static UINT32 Base_GranulatedSize( UINT32 ulSize, UINT32 ulGranularity = 1 )
	{
		return( ((ulSize + ulGranularity - 1) / ulGranularity) * ulGranularity );
	}

   /*
	** CBigByteQueue()
	*
	*  PARAMETERS:
	*	void
	*
	*  DESCRIPTION:
	*	Default constructor:  We hide this guy because we want to enforce
	*	the parameterized constructor.
	*	We might at some later time relax that restriction and allow
	*	a two step creation process, but not for now.
	*
	*  RETURNS:
	*	void
	*/
	CBigByteQueue()	{}

   /*
	** UINT32 Base_PeekBuff( pOutBuffer, ulByteCount )
	*
	*  PARAMETERS:
	*	pOutBuffer		Pointer to buffer to receive bytes.
	*	ulByteCount		Desired max bytes to copy out of queue.
	*
	*  DESCRIPTION:
	*	Copies bytes (nByteCount) from the Queue head to pOutBuffer.
	*	returns the number of bytess actually copied into pOutBuffer.
	*	This function does NOT modify the queue.  It is strictly a 
	*	peek of the queue bytes specified.
	*	Our limiting factor is:
	*		 min( ulByteCount, Base_GetUsedByteCount() ).
	*
	*  RETURNS:
	*	Number of bytes copied into pOutBuffer.
	*/
	UINT32 Base_PeekBuff( void *pOutBuffer, UINT32 ulByteCount ) const;


};	//	class CBigByteQueue

#endif	//	if !defined( _CBBQUEUE_H_ )