Whatever message this page gives is out now! Go check it out!
CCFXRequest class
Last update:
May 18, 2026
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 interfaces that can be used by the custom extension for the following actions:
- Reading and writing variables
- Returning output
- Creating and using queries
- Throwing exceptions
Class methods
virtual BOOL AttributeExists( LPCSTR lpszName ) | :AttributeExists checks whether the attribute was passed to the tag. |
virtual LPCSTR GetAttribute( LPCSTR lpszName ) | :GetAttribute gets the value of the passed attribute. |
virtual CCFXStringSet* GetAttributeList() | :GetAttributeList gets an array of attribute names passed to the tag. |
virtual CCFXQuery* GetQuery() | :GetQuery gets the query that was passed to the tag. |
virtual LPCSTR GetSetting( LPCSTR lpszSettingName ) | {{CCFXRequest::GetSetting}}This method is deprecated. It might not work, and might cause an error, in later releases. |
virtual void Write( LPCSTR lpszOutput ) | :Write writes text output back to the user. |
virtual void SetVariable( LPCSTR lpszName, LPCSTR lpszValue ) | :SetVariable sets a variable in the template that contains this tag. |
virtual CCFXQuery* AddQuery( LPCSTR lpszName, CCFXStringSet* pColumns ) | :AddQuery adds a query to the template that contains this tag. |
virtual BOOL Debug() | :Debug checks whether the tag contains the Debug attribute. |
virtual void WriteDebug( LPCSTR lpszOutput ) | :WriteDebug writes text output into the debug stream. |
virtual CCFXStringSet* CreateStringSet() | :CreateStringSet allocates and returns a CCFXStringSet instance. |
virtual void ThrowException( LPCSTR lpszError, LPCSTR lpszDiagnostics ) | :ThrowException throws an exception and ends processing of this request. |
virtual void ReThrowException( CCFXException* e ) | :ReThrowException rethrows an exception that has been caught. |
virtual void SetCustomData( LPVOID lpvData ) | :SetCustomData sets custom (tag specific) data to carry with a request. |
virtual LPVOID GetCustomData() | :GetCustomData gets custom (tag specific) data for a request. |
CCFXRequest::AddQuery
Syntax
CCFXQuery* CCFXRequest::AddQuery(LPCSTR lpszName, CCFXStringSet* pColumns) |
Description
Adds a query to the calling template. The query can be accessed by CFML tags (for example, cfoutput or cftable) within the template. After calling AddQuery, the query is empty (it has 0 rows). To populate the query with data, call the :AddRow and :SetData functions.
Returns
Returns a pointer to the query that was added to the template (an object of class CCFXQuery). The memory allocated for the returned query is freed automatically by ColdFusion after the request is completed.
Parameters
| Parameter | Description |
lpszName | Name of query to add to the template (must be unique) |
pColumns | List of column 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
Syntax
BOOL CCFXRequest::AttributeExists(LPCSTR lpszName) |
Description
Checks whether the parameter was passed to the tag. Returns True if the parameter is available; False, otherwise.
Parameters
| Parameter | Description |
lpszName | Name of the parameter to check (case insensitive) |
Example
The following example checks whether 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
Syntax
CCFXStringSet* CCFXRequest::CreateStringSet(void) |
Description
Allocates and returns an instance. Always use this function to create string sets, as opposed to directly using the new operator.
Returns
Returns an object of CCFXStringSet class . The memory allocated for the returned string set is freed automatically by ColdFusion after the request is completed
Example
The following example creates a string set and adds three strings to it:
CCFXStringSet* pColors = pRequest->CreateStringSet() ; pColors->AddString( "Red" ) ; pColors->AddString( "Green" ) ; pColors->AddString( "Blue" ) ; |
CCFXRequest::Debug
Syntax
BOOL CCFXRequest::Debug(void) |
Description
Checks whether the tag contains the Debug attribute. Use this function to determine whether to write debug information for a request. For more information, see :WriteDebug.
Returns
Returns True if the tag contains the Debug attribute; False, otherwise.
Example
The following example checks 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
Syntax
LPCSTR CCFXRequest::GetAttribute(LPCSTR lpszName) |
Description
Retrieves the value of the passed attribute. Returns an empty string if the attribute does not exist. (To test whether an attribute was passed to the tag, use :AttributeExists.)
Returns
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.
Parameters
| Parameter | Description |
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
Syntax
CCFXStringSet* CCFXRequest::GetAttributeList(void) |
Description
Gets an array of attribute names passed to the tag. To get the value of one attribute, use :GetAttribute.
Returns
Returns an object of class CCFXStringSet class that contains a list of attributes passed to the tag. The memory allocated for the returned string set is freed automatically by ColdFusion after the request is completed.
Example
The following example gets the list of attributes and 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
Syntax
LPVOID CCFXRequest::GetCustomData(void) |
Description
Gets the custom (tag specific) data for the request. This method is typically used from within subroutines of a tag implementation to extract tag data from a request.
Returns
Returns a pointer to the custom data, or NULL if no custom data has been set during this request using :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
Syntax
CCFXQuery* CCFXRequest::GetQuery(void) |
Description
Retrieves a query that was passed to a tag. To pass a query to a custom tag, you use the QUERY attribute. Set the attribute to the name of a query (created using the cfquery tag or another custom tag). The QUERY attribute is optional and must be used only by tags that process an existing data set.
Returns
Returns an object of the CCFXQuery class that represents the query passed to the tag. If no query was passed to the tag, NULL is returned. The memory allocated for the returned query is 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::ReThrowException
Syntax
void CCFXRequest::ReThrowException(CCFXException* e) |
Description
Rethrows an exception that has been caught within an extension procedure. This function is used to avoid having C++ exceptions that are thrown by DLL extension code propagate back into ColdFusion. Catch ALL C++ exceptions that occur in extension code, and either re-throw them (if they are of the CCFXException class ) or create and throw a new exception pointer using :ThrowException.
Parameters
| Parameter | Description |
e | A CCFXException that has been caught |
Example
The following code demonstrates how 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
Syntax
void CCFXRequest::SetCustomData(LPVOID lpvData) |
Description
Sets custom (tag specific) data to carry with the request. Use this function to store request specific data to pass to procedures within your custom tag implementation.
Parameters
| Parameter | Description |
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
Syntax
void CCFXRequest::SetVariable(LPCSTR lpszName, LPCSTR lpszValue) |
Description
Sets a variable in the calling template. If the variable name already exists in the template, its value is replaced. If it does not exist, a variable is created. The values of variables created using SetVariable can be accessed in the same manner as other template variables (for example, #MessageSent#).
Parameters
| Parameter | Description |
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
Syntax
void CCFXRequest::ThrowException(LPCSTR lpszError, LPCSTR lpszDiagnostics) |
Description
Throws an exception and ends processing of a request. Call this function when you encounter an error that does not allow you to continue processing the request. This function is almost always combined with the :ReThrowException to protect against resource leaks in extension code.
Parameters
| Parameter | Description |
lpszError | Short identifier for error |
lpszDiagnostics | Error diagnostic information |
Example
The following example throws an exception indicating that an unexpected error occurred while processing a request:
char buffError[512] ; wsprintf( buffError, "Unexpected Windows NT error number %ld " "occurred while processing request.", GetLastError() ) ; pRequest->ThrowException( "Error occurred", buffError ) ; |
CCFXRequest::Write
Syntax
void CCFXRequest::Write(LPCSTR lpszOutput) |
Description
Writes text output back to the user.
Parameters
| Parameter | Description |
lpszOutput | Text to output |
Example
The following example creates a buffer to hold an output string, fills the buffer with data, and writes the output back to the user:
CHAR buffOutput[1024] ; wsprintf( buffOutput, "The destination is: %s", pRequest->GetAttribute("DESTINATION") ) ; pRequest->Write( buffOutput ) ; |
CCFXRequest::WriteDebug
Syntax
void CCFXRequest::WriteDebug(LPCSTR lpszOutput) |
Description
Writes text output into the debug stream. The text is only displayed to the end user if the tag contains the Debug attribute. (For more information, see :Debug.)
Parameters
| Parameter | Description |
lpszOutput | Text to output |
Example
The following example checks whether the Debug attribute is present; if so, it writes a brief debug message:
if ( pRequest->Debug() ) { pRequest->WriteDebug( "Top secret debug info" ) ; } |
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
