# CCFXRequest Class

Abstract class that represents a request made to a ColdFusion Extension (CFX). An instance of this class is passed to the main function of your extension DLL. The class provides several interfaces that may be used by the custom extension, including functions for reading and writing variables, returning output, creating and using queries, and throwing exceptions.

## Class Members

    virtual BOOL AttributeExists( LPCSTR lpszName )

CCFXRequest::AttributeExists checks to see whether the attribute was passed to the tag.

virtual LPCSTR GetAttribute( LPCSTR lpszName )

CCFXRequest::GetAttribute retrieves the value of the passed attribute.

virtual CCFXStringSet* GetAttributeList()

CCFXRequest::GetAttributeList retrieves a list of all attribute names passed to the tag.

virtual CCFXQuery* GetQuery()

CCFXRequest::GetQuery retrieves the query that was passed to the tag.

virtual LPCSTR GetSetting( LPCSTR lpszSettingName )

CCFXRequest::GetSetting retrieves the value of a custom tag setting.

virtual void Write( LPCSTR lpszOutput )

CCFXRequest::Write writes text output back to the user.

virtual void SetVariable( LPCSTR lpszName, LPCSTR lpszValue )

CCFXRequest::SetVariable sets a variable in the template that contains this tag.

virtual CCFXQuery* AddQuery( LPCSTR lpszName, CCFXStringSet* pColumns )

CCFXRequest::AddQuery adds a query to the template that contains this tag.

virtual BOOL Debug()

CCFXRequest::Debug checks whether the tag contains the `DEBUG` attribute.

virtual void WriteDebug( LPCSTR lpszOutput )

CCFXRequest::WriteDebug writes text output into the debug stream.

virtual CCFXStringSet* CreateStringSet()

CCFXRequest::CreateStringSet allocates and returns a new `CCFXStringSet` instance.

virtual void ThrowException( LPCSTR lpszError, LPCSTR lpszDiagnostics )

CCFXRequest::ThrowException throws an exception and ends processing of this request.

virtual void ReThrowException( CCFXException* e )

CCFXRequest::ReThrowException re-throws an exception that has been caught.

virtual void SetCustomData( LPVOID lpvData )

CCFXRequest::SetCustomData sets custom (tag specific) data to carry along with the request.

virtual LPVOID GetCustomData()

CCFXRequest::GetCustomData gets the custom (tag specific) data for the request.

## CCFXRequest::AddQuery

    CCFXQuery* CCFXRequest::AddQuery(LPCSTR lpszName, CCFXStringSet*
    pColumns)

Adds a query to the calling template. This query can then be accessed by CFML tags (for example, `CFOUTPUT` or `CFTABLE`) within the template. Note that after calling `AddQuery`, the query exists but is empty (that is, it has 0 rows). To populate the query with data, you should call the CCFXQuery::AddRow and CCFXQuery::SetData functions.

Returns a pointer to the query that was added to the template (an object of class `CCFXQuery`). You are not responsible for freeing the memory allocated for the returned query (it will be freed automatically by ColdFusion after the request is completed).

    lpszName

Name of query to add to the template (must be unique).

pColumns

List of columns names to be used in the query.

#### Example

The following example adds a query named 'People' to the calling template. The query has two columns ('FirstName' and 'LastName') and two rows:

    // Create a string set and add the column names to it
    CCFXStringSet* pColumns = pRequest->CreateStringSet() ;
    int iFirstName = pColumns->AddString( "FirstName" ) ;
    int iLastName = pColumns->AddString( "LastName" ) ;

    // Create a query that contains these columns
    CCFXQuery* pQuery = pRequest->AddQuery( "People", pColumns ) ;

    // Add data to the query
    int iRow ;
    iRow = pQuery->AddRow() ;
    pQuery->SetData( iRow, iFirstName, "John" ) ;
    pQuery->SetData( iRow, iLastName, "Smith" ) ;
    iRow = pQuery->AddRow() ;
    pQuery->SetData( iRow, iFirstName, "Jane" ) ;
    pQuery->SetData( iRow, iLastName, "Doe" ) ;

## CCFXRequest::AttributeExists

    BOOL CCFXRequest::AttributeExists(LPCSTR lpszName)

Checks to see whether the attribute was passed to the tag. Returns TRUE if the attribute is available; otherwise, returns FALSE.

    lpszName

Name of the attribute to check (case insensitive).

#### Example

The following example checks to see if the user passed an attribute named DESTINATION to the tag and throws an exception if the attribute was not passed:

    if ( pRequest->AttributeExists("DESTINATION")==FALSE )
    {
        pRequest->ThrowException(
            "Missing DESTINATION parameter",
            "You must pass a DESTINATION parameter in "
            "order for this tag to work correctly." ) ;
    }

## CCFXRequest::CreateStringSet

    CCFXStringSet* CCFXRequest::CreateStringSet(void)

Allocates and returns a new instance. Note that string sets should always be created using this function as opposed to directly using the 'new' operator.

Returns an object of CCFXStringSet Class. You are not responsible for freeing the memory allocated for the returned string set (it will be freed automatically by ColdFusion after the request is completed).

#### Example

The following example creates a string set and adds 3 strings to it:

    CCFXStringSet* pColors = pRequest->CreateStringSet() ;
    pColors->AddString( "Red" ) ;
    pColors->AddString( "Green" ) ;
    pColors->AddString( "Blue" ) ;

## CCFXRequest::Debug

    BOOL CCFXRequest::Debug(void)

Checks whether the tag contains the `DEBUG` attribute. You should use this function to determine whether or not you need to write debug information for this request. (See the CCFXRequest::WriteDebug tag for details on writing debug information.)

Returns `TRUE` if the tag contains the `DEBUG` attribute; otherwise, returns `FALSE`.

#### Example

The following example checks to see whether the `DEBUG` attribute is present, and if it is, it writes a brief debug message:

    if ( pRequest->Debug() )
    {
            pRequest->WriteDebug( "Top secret debug info" ) ;
    }

## CCFXRequest::GetAttribute

    LPCSTR CCFXRequest::GetAttribute(LPCSTR lpszName)

Retrieves the value of the passed attribute. Returns an empty string if the attribute does not exist. (Use CCFXRequest::AttributeExists to test whether an attribute was passed to the tag.)

Returns the value of the attribute passed to the tag. If no attribute of that name was passed to the tag, an empty string is returned.

    lpszName

Name of the attribute to retrieve (case insensitive).

#### Example

The following example retrieves an attribute named `DESTINATION` and writes its value back to the user:

    LPCSTR lpszDestination = pRequest->GetAttribute("DESTINATION") ;
    pRequest->Write( "The destination is: " ) ;
    pRequest->Write( lpszDestination ) ;

## CCFXRequest::GetAttributeList

    CCFXStringSet* CCFXRequest::GetAttributeList(void)

Retrieves a list of all attribute names passed to the tag. To retrieve the value of an individual attribute, you should use CCFXRequest::GetAttribute.

Returns an object of class CCFXStringSet Class that contains a list of all attributes passed to the tag.

You are not responsible for freeing the memory allocated for the returned string set (it will be freed automatically by ColdFusion after the request is completed).

#### Example

The following example retrieves the list of attributes and then iterates over the list, writing each attribute and its value back to the user.

    LPCSTR lpszName, lpszValue ;
    CCFXStringSet* pAttribs = pRequest->GetAttributeList() ;
    int nNumAttribs = pAttribs->GetCount() ;

    for( int i=1; i<=nNumAttribs; i++ )
    {
            lpszName = pAttribs->GetString( i ) ;
            lpszValue = pRequest->GetAttribute( lpszName ) ;
            pRequest->Write( lpszName ) ;
            pRequest->Write( " = " ) ;
            pRequest->Write( lpszValue ) ;
            pRequest->Write( "<BR>" ) ;
    }

## CCFXRequest::GetCustomData

    LPVOID CCFXRequest::GetCustomData(void)

Gets the custom (tag specific) data for the request. This member is typically used from within subroutines of your tag implementation to extract tag specific data from within the request.

Returns a pointer to the custom data or returns `NULL` if no custom data has been set during this request using CCFXRequest::SetCustomData.

#### Example

The following example retrieves a pointer to a request specific data structure of hypothetical type MYTAGDATA:

    void DoSomeGruntWork( CCFXRequest* pRequest )
    {
            MYTAGDATA* pTagData =
                (MYTAGDATA*)pRequest->GetCustomData() ;

            ... remainder of procedure ...
    }

## CCFXRequest::GetQuery

    CCFXQuery* CCFXRequest::GetQuery(void)

Retrieves the query that was passed to the tag. To pass a query to a custom tag, you use the `QUERY` attribute. This attribute should be set to the name of an existing query (created using the CFQUERY tag or another custom tag). The `QUERY` attribute is optional and should only be used by tags that need to process an existing data set.

Returns an object of the CCFXQuery Class that represents the query that was passed to the tag. If no query was passed to the tag, `NULL` is returned. You are not responsible for freeing the memory allocated for the returned query (it will be freed automatically by ColdFusion after the request is completed).

#### Example

The following example retrieves the query that was passed to the tag. If no query was passed, an exception is thrown:

    CCFXQuery* pQuery = pRequest->GetQuery() ;
    if ( pQuery == NULL )
    {
            pRequest->ThrowException(
                "Missing QUERY parameter",
                "You must pass a QUERY parameter in "
                "order for this tag to work correctly." ) ;
    }

## CCFXRequest::GetSetting

    LPCSTR CCFXRequest::GetSetting(LPCSTR lpszSettingName)

Retrieves the value of a global custom tag setting. Custom tag settings are stored within the CustomTags section of the ColdFusion Registry key.

Returns the value of the custom tag setting. If no setting of that name exists, an empty string is returned.

    lpszSettingName

Name of the setting to retrieve (case insensitive).

#### Example

The following example retrieves the value of a setting named 'VerifyAddress' and uses the returned value to determine what actions to take next:

    LPCSTR lpszVerify = pRequest->GetSetting("VerifyAddress") ;
    BOOL bVerify = atoi(lpszVerify) ;
    if ( bVerify == TRUE )
    {
            // Do address verification...
    }

## CCFXRequest::ReThrowException

    void CCFXRequest::ReThrowException(CCFXException* e)

Re-throws an exception that has been caught within an extension procedure. This function is used to avoid having C++ exceptions thrown by DLL extension code propagate back into ColdFusion. You should catch ALL C++ exceptions that occur in your extension code and then either re-throw them (if they are of the CCFXException Class) or create and throw a new exception pointer using CCFXRequest::ThrowException.

    e

An existing CCFXException that has been caught.

#### Example

The following code demonstrates the correct way to handle exceptions in ColdFusion Extension DLL procedures:

    try
    {

            ...Code that could throw an exception...

    }
    catch( CCFXException* e )
    {
            ...Do appropriate resource cleanup here...

            // Re-throw the exception
            pRequest->ReThrowException( e ) ;
    }
    catch( ... )
    {
            // Something nasty happened

            pRequest->ThrowException(
                "Unexpected error occurred in CFX tag", "" ) ;
    }

## CCFXRequest::SetCustomData

    void CCFXRequest::SetCustomData(LPVOID lpvData)

Sets custom (tag specific) data to carry along with the request. You should use this function to store request specific data that you want to pass along to procedures within your custom tag implementation.

    lpvData

Pointer to custom data.

#### Example

The following example creates a request-specific data structure of hypothetical type MYTAGDATA and stores a pointer to the structure in the request for future use:

    void ProcessTagRequest( CCFXRequest* pRequest )
    {
            try
            {
                MYTAGDATA tagData ;
                pRequest->SetCustomData( (LPVOID)&tagData ) ;

            ... remainder of procedure ...
    }

## CCFXRequest::SetVariable

    void CCFXRequest::SetVariable(LPCSTR lpszName, LPCSTR lpszValue)

Sets a variable in the calling template. If the variable name specified already exists in the template, its value is replaced. If it does not already exist, a new variable is created. The values of variables created using `SetVariable` can be accessed in the same manner as other template variables (e.g., #MessageSent#).

    lpszName

Name of variable.

lpszValue

Value of variable.

#### Example

The following example sets the value of a variable named `'MessageSent'` based on the success of an operation performed by the custom tag:

    BOOL bMessageSent ;

    ...attempt to send the message...

    if ( bMessageSent == TRUE )
    {
            pRequest->SetVariable( "MessageSent", "Yes" ) ;
    }
    else
    {
            pRequest->SetVariable( "MessageSent", "No" ) ;
    }

## CCFXRequest::ThrowException

    void CCFXRequest::ThrowException(LPCSTR lpszError, LPCSTR
    lpszDiagnostics)

Throws an exception and ends processing of this request. You should call this function when you encounter an error that does not allow you to continue processing the request. Note that this function is almost always combined with the CCFXRequest::ReThrowException to provide protection against resource leaks in extension code.

    lpszError

Short identifier for error.

lpszDiagnostics

Error diagnostic information.

#### Example

The following example throws an exception indicating that an unexpected error occurred while processing the request:

    char buffError[512] ;
    wsprintf( buffError,
            "Unexpected Windows NT error number %ld "
            "occurred while processing request.", GetLastError() ) ;

    pRequest->ThrowException( "Error occurred", buffError ) ;

## CCFXRequest::Write

    void CCFXRequest::Write(LPCSTR lpszOutput)

Writes text output back to the user.

    lpszOutput

Text to output.

#### Example

The following example creates a buffer to hold an output string, fills the buffer with data, and then writes the output back to the user:

    CHAR buffOutput[1024] ;
    wsprintf( buffOutput, "The destination is: %s",
            pRequest->GetAttribute("DESTINATION") ) ;
    pRequest->Write( buffOutput ) ;

## CCFXRequest::WriteDebug

    void CCFXRequest::WriteDebug(LPCSTR lpszOutput)

Writes text output into the debug stream. This text is only displayed to the end-user if the tag contains the `DEBUG` attribute. (For more information, see CCFXRequest::Debug.)

    lpszOutput

Text to output.

#### Example

The following example checks to see whether the DEBUG attribute is present, and if it is, it writes a brief debug message:

    if ( pRequest->Debug() )
    {
            pRequest->WriteDebug( "Top secret debug info" ) ;
    }