Burger::CaptureStdout Class Reference

Class to capture stdout and stderr. More...

Collaboration diagram for Burger::CaptureStdout:

Public Member Functions
	CaptureStdout () noexcept
	Construct a CaptureStdout class.
	~CaptureStdout ()
	Destroy a CaptureStdout class.
eError	Init (uintptr_t uBufferSize=65536U) noexcept
	Intercept stdout and stderr.
eError	Shutdown (void) noexcept
	Restore stdout and stderr.
eError	GetCapture (String *pOutput) noexcept
	Store the contents of the pipe into a string.

Private Member Functions
	CaptureStdout (const CaptureStdout &)=delete
CaptureStdout &	operator= (const CaptureStdout &)=delete
	CaptureStdout (CaptureStdout &&)=delete
CaptureStdout &	operator= (CaptureStdout &&)=delete

Static Private Member Functions
static int	ReadIntercept (unsigned long pFile, unsigned char *pBuff, uintptr_t *pCount, void *pThat)
	Intercept input from FILE streams.
static int	WriteIntercept (unsigned long pFile, unsigned char *pBuff, uintptr_t *pCount, void *pThat)
	Intercept output from FILE streams.
static int	SeekIntercept (unsigned long pFile, unsigned long *pPosition, int mode, void *pThat)
	Intercept seek from FILE streams.

Private Attributes
uintptr_t	m_uCaptureSize
	Maximum size of the capture pipe.
uint_t	m_bActive
	TRUE if currently capturing stream output
int	m_iInputPipe
	New input pipe.
int	m_iOutputPipe
	New output pipe.
int	m_iPreviousStdout
	Previous stdout pipe.
int	m_iPreviousStderr
	Previous stderr pipe.
void *	m_pSaved [2 *4]
	Saved function pointers from stdout, stderr.
OutputMemoryStream	m_Stream
	Memory stream for capturing output.

Detailed Description

Class to capture stdout and stderr.

---

For quick redirection of the stdout and stderr output stream, create an instance of this class, and when capturing is needed create code like the example below.

void foo()
{
    Burger::CaptureStdout Capture;
 
    // Use a small buffer.
    Capture.Init(128);
 
    // Send text to stdout.
    printf("Hello World!");
 
    // Obtain the captured text.
    Burger::String Text;
    if (Capture.GetCapture(&Text) == Burger::kErrorNone) {
        // Capture was successful.
        // Text will contain "Hello World!" and nothing will have been
        // printed to the console.
    }
 
    // Stop capturing and release buffers
    Capture.Shutdown();
}

Note

This class affects stdout and stderr globally. Use this class with caution.

See also

Burger::OutputMemoryStream

Constructor & Destructor Documentation

CaptureStdout() [1/3]

Burger::CaptureStdout::CaptureStdout ( const CaptureStdout & )

privatedelete

CaptureStdout() [2/3]

Burger::CaptureStdout::CaptureStdout ( CaptureStdout && )

privatedelete

CaptureStdout() [3/3]

Burger::CaptureStdout::CaptureStdout ( )

noexcept

Construct a CaptureStdout class.

---

~CaptureStdout()

Burger::CaptureStdout::~CaptureStdout

(

)

Destroy a CaptureStdout class.

---

Member Function Documentation

GetCapture()

Burger::eError BURGER_API Burger::CaptureStdout::GetCapture ( String * pOutput )

noexcept

Store the contents of the pipe into a string.

---

Flush the pipe and store the contents of the pipe into a passed String class instance. After this call, the interception pipe is reset so it can be refilled with intercepted output.

Parameters

pOutput

Pointer to a String to store the data

Returns

Error code

See also

Init(uintptr_t) or Shutdown(void)

Init()

Burger::eError BURGER_API Burger::CaptureStdout::Init ( uintptr_t uBufferSize = 65536U )

noexcept

Intercept stdout and stderr.

---

Create a pipe with a specific byte length and redirect stdout and stderr into the new pipe.

Parameters

uBufferSize

Number of bytes to allocate for the pipe's buffer

Returns

Error code

See also

Shutdown(void) or GetCapture(String *)

operator=() [1/2]

CaptureStdout & Burger::CaptureStdout::operator= ( CaptureStdout && )

privatedelete

operator=() [2/2]

CaptureStdout & Burger::CaptureStdout::operator= ( const CaptureStdout & )

privatedelete

ReadIntercept()

int BURGER_ANSIAPI Burger::CaptureStdout::ReadIntercept ( unsigned long pFile, unsigned char * pBuff, uintptr_t * pCount, void * pThat )

staticprivate

Intercept input from FILE streams.

---

Return error

Parameters

pFile	Not used.
pBuff	Not used.
pCount	Not used.
pThat	Not used.

Returns

EOF error.

Note

Only available with the Metrowerks compiler.

SeekIntercept()

int BURGER_ANSIAPI Burger::CaptureStdout::SeekIntercept ( unsigned long pFile, unsigned long * pPosition, int mode, void * pThat )

staticprivate

Intercept seek from FILE streams.

---

Return error

Parameters

pFile	Not used.
pPosition	Not used.
mode	Not used.
pThat	Not used.

Returns

I/O error.

Note

Only available with the Metrowerks compiler.

Shutdown()

Burger::eError BURGER_API Burger::CaptureStdout::Shutdown ( void )

noexcept

Restore stdout and stderr.

---

Detach the interception pipe and dispose of the pipe.

Returns

Error code

See also

Init(uintptr_t) or GetCapture(String *)

WriteIntercept()

int BURGER_ANSIAPI Burger::CaptureStdout::WriteIntercept ( unsigned long pFile, unsigned char * pBuff, uintptr_t * pCount, void * pThat )

staticprivate

Intercept output from FILE streams.

---

The Metrowerks Standard Library uses a hard coded array of FILE records for stdin, stdout, stderr and null (In that order). Due to this, pipe is not supported, and hocus pocus is required to handle stream interception. This function replaces the write_proc callback to capture the text output.

Parameters

pFile	Index into the __files array, 1 = stdout, 2 = stderr.
pBuff	Bytes to transfer.
pCount	Pointer to a count of bytes to transfer.
pThat	Pointer to the Burger::CaptureStdout instance.

Returns

Error code or zero if no error.

Note

Only available with the Metrowerks compiler.

Member Data Documentation

m_bActive

uint_t Burger::CaptureStdout::m_bActive

private

TRUE if currently capturing stream output

m_iInputPipe

int Burger::CaptureStdout::m_iInputPipe

private

New input pipe.

m_iOutputPipe

int Burger::CaptureStdout::m_iOutputPipe

private

New output pipe.

m_iPreviousStderr

int Burger::CaptureStdout::m_iPreviousStderr

private

Previous stderr pipe.

m_iPreviousStdout

int Burger::CaptureStdout::m_iPreviousStdout

private

Previous stdout pipe.

m_pSaved

void* Burger::CaptureStdout::m_pSaved[2 *4]

private

Saved function pointers from stdout, stderr.

m_Stream

OutputMemoryStream Burger::CaptureStdout::m_Stream

private

Memory stream for capturing output.

m_uCaptureSize

uintptr_t Burger::CaptureStdout::m_uCaptureSize

private

Maximum size of the capture pipe.