home *** CD-ROM | disk | FTP | other *** search
/ Computer Shopper 139 / dpcs0999.iso / Web / CFserver / data1.cab / CFX_Wizard / include / cfx.h
Encoding:
C/C++ Source or Header  |  1999-04-12  |  32.7 KB  |  977 lines
  1. /////////////////////////////////////////////////////////////////////
  2. // Standard headers for ColdFusion extensions (CFX)
  3. //
  4. // Copyright 1996 Allaire Corp. 
  5. // All Rights Reserved.
  6. //
  7. // @doc 
  8. // (use AutoDuck to generate documentation)
  9. //
  10. // @contents1 ColdFusion Extension API | 
  11.  
  12. // @index class |
  13.  
  14.  
  15. #ifndef __CFX_H__
  16. #define __CFX_H__
  17.  
  18.  
  19. // Forward declarations
  20. class CCFXException ;
  21. class CCFXStringSet ;
  22. class CCFXQuery ;
  23.  
  24.  
  25. /////////////////////////////////////////////////////////////////////
  26. // CCFXRequest 
  27.  
  28. // @class Abstract class which represents a request made
  29. //        to a ColdFusion Extension (CFX). An instance of
  30. //        this class is passed to the main function of your
  31. //        extension DLL. The class provides several interfaces which may
  32. //        be used by the custom extension including functions
  33. //        for reading and writing variables, returning output,
  34. //        creating and using queries, and throwing exceptions.
  35. //
  36. class CCFXRequest
  37. {
  38. // Construction/Destruction
  39. public:
  40.     virtual ~CCFXRequest() {} ;
  41.  
  42. // Operations
  43. public:
  44.     // Retreiving data from the template
  45.     
  46.     // @cmember Checks to see whether the attribute was passed
  47.     //          to the tag.
  48.     virtual BOOL AttributeExists( LPCSTR lpszName ) = 0 ;
  49.     
  50.     // @cmember Retrieves the value of the passed attribute.
  51.     virtual LPCSTR GetAttribute( LPCSTR lpszName ) = 0 ;
  52.         
  53.     // @cmember Retrieves a list of all attribute names passed to the tag.
  54.     virtual CCFXStringSet* GetAttributeList() = 0 ;
  55.     
  56.     // @cmember Retrieves the query which was passed to the tag.
  57.     virtual CCFXQuery* GetQuery() = 0 ;    
  58.  
  59.     // @cmember Retrieves the value of a custom tag setting.
  60.     virtual LPCSTR GetSetting( LPCSTR lpszSettingName ) = 0 ;
  61.  
  62.     // Returning data to the template
  63.     
  64.     // @cmember Writes text output back to the user.
  65.     virtual void Write( LPCSTR lpszOutput ) = 0 ;
  66.     
  67.     // @cmember Sets a variable in the template which contains this tag.
  68.     virtual void SetVariable(  LPCSTR lpszName, LPCSTR lpszValue ) = 0 ;
  69.     
  70.     // @cmember Adds a query to the template which contains this tag.
  71.     virtual CCFXQuery* AddQuery( LPCSTR lpszName, CCFXStringSet* pColumns ) = 0 ;
  72.  
  73.     // Debugging support
  74.     
  75.     // @cmember Checks whether the tag contains the DEBUG attribute.
  76.     virtual BOOL Debug() = 0 ;
  77.  
  78.     // @cmember Writes text output into the debug stream.
  79.     virtual void WriteDebug( LPCSTR lpszOutput ) = 0 ;
  80.  
  81.     // Allocating a string set instance (should NEVER be done
  82.     // directly (e.g. w/ 'new') by extensions
  83.     
  84.     // @cmember Allocates and returns a new CCFXStringSet instance.
  85.     virtual CCFXStringSet* CreateStringSet() = 0 ;
  86.  
  87.     // Throwing exceptions in the case of errors (should NEVER
  88.     // throw an exception directly from within a custom tag
  89.     
  90.     // @cmember Throws an exception and ends processing of this request.
  91.     virtual void ThrowException( 
  92.         LPCSTR lpszError, LPCSTR lpszDiagnostics ) = 0 ;
  93.     
  94.     // @cmember Re-throws an exception which has been caught.
  95.     virtual void ReThrowException( CCFXException* e ) = 0 ;
  96.  
  97.     
  98.     // Custom data
  99.  
  100.     // @cmember Sets custom (tag specific) data to carry along with the request.
  101.     virtual void SetCustomData( LPVOID lpvData ) = 0 ;
  102.  
  103.     // @cmember Gets the custom (tag specific) data for the request
  104.     virtual LPVOID GetCustomData() = 0 ;
  105. } ;
  106.  
  107.  
  108.  
  109. /////////////////////////////////////////////////////////////////////
  110. // CCFXQuery -  Abstract class which represents a query used
  111. //              or created by a ColdFusion extension (CFX)
  112.  
  113. // @class   Abstract class which represents a query used
  114. //          or created by a ColdFusion Extension (CFX). Queries
  115. //          contain 1 or more columns of data which extend over
  116. //          a varying number of rows.
  117. class CCFXQuery
  118. {
  119. // Construction/Destruction
  120. public:
  121.     virtual ~CCFXQuery() {} ;
  122.  
  123. // Operations
  124. public:  
  125.     // Retreiving data from the query
  126.     
  127.     // @cmember Retrieves the name of the query.
  128.     virtual LPCSTR GetName() = 0 ;
  129.  
  130.     // @cmember Retrieves the number of rows in the query.
  131.     virtual int GetRowCount() = 0 ;
  132.  
  133.     // @cmember Retrieves a list of the query's column names.
  134.     virtual CCFXStringSet* GetColumns() = 0 ;
  135.  
  136.     // @cmember Retrieve a data element from a row and column of the query.
  137.     virtual LPCSTR GetData( int iRow, int iColumn ) = 0 ;
  138.  
  139.     // Adding data to the query
  140.  
  141.     // @cmember Add a new row to the query.
  142.     virtual int AddRow() = 0 ;    
  143.     
  144.     // @cmember Set a data element within a row and column of the query.
  145.     virtual void SetData( int iRow, int iColumn, LPCSTR lpszData ) = 0 ;
  146.     
  147.     // Setting query debug attributes
  148.  
  149.     // @cmember Set the query string which will displayed along with
  150.     //          query debug output.
  151.     // This call is  deprecated. No-op.
  152.     virtual void SetQueryString( LPCSTR lpszQuery ) = 0 ;
  153.     
  154.     // @cmember Set the total time which was required to process the
  155.     //          query (used for debug outupt). 
  156.     // This call is  deprecated. No-op.
  157.     virtual void SetTotalTime( DWORD dwMilliseconds ) = 0 ;
  158. } ;
  159.  
  160.  
  161. /////////////////////////////////////////////////////////////////////
  162. // CCFXStringSet - Class which represents a set of ordered
  163. //                 strings (used extensively in the ColdFusion 
  164. //                 extension interface)
  165.  
  166. #define CFX_STRING_NOT_FOUND    -1
  167.  
  168. // @class Abstract class which represents a set of 
  169. //        ordered strings. Strings can be added to
  170. //        set and can be retrieved by numeric index (the 
  171. //        index values for strings are 1-based).
  172. //          To create a string set you should use the 
  173. //          CCFXRequest member function <mf CCFXRequest::CreateStringSet>.
  174. //
  175. class CCFXStringSet
  176. {
  177. // Construction/Destruction
  178. public:
  179.     virtual ~CCFXStringSet() {} ;
  180.  
  181. // Operations
  182. public:
  183.     // Adding strings to the collection
  184.     
  185.     // @cmember Add a string to the end of the list.
  186.     virtual int AddString( LPCSTR lpszString ) = 0 ;
  187.  
  188.     // Retreiving strings from the collection
  189.  
  190.     // @cmember Get the number of strings contained in the list.
  191.     virtual int GetCount() = 0 ;
  192.  
  193.     // @cmember Get the string located at the passed index.
  194.     virtual LPCSTR GetString( int iIndex ) = 0 ;
  195.  
  196.     // @cmember Get the index for the passed string.
  197.     virtual int GetIndexForString( LPCSTR lpszString ) = 0 ;
  198. } ;
  199.  
  200.  
  201. /////////////////////////////////////////////////////////////////////
  202. // CCFXException - Class which represents an exception thrown
  203. //                 by the ColdFusion Extension (CFX) library 
  204.  
  205. // @class Abstract class which represents an exception thrown
  206. //        during the processing of a ColdFusion Extension (CFX)
  207. //          procedure.<nl>
  208. //        <nl>Exceptions of this type can be thrown by
  209. //          the classes <c CCFXRequest>, <c CCFXQuery>, and 
  210. //          <c CCFXStringSet>. Your ColdFusion Extension code must
  211. //        therefore be written to handle exceptions of this type
  212. //          (see CCFXRequest::ReThrowException for more details on
  213. //        doing this correctly).
  214. class CCFXException
  215. {
  216. // Construction/Destruction
  217. public:
  218.     virtual ~CCFXException() {} ;
  219.     virtual LPCSTR GetError() = 0;
  220.     virtual LPCSTR GetDiagnostics() = 0;
  221. } ;
  222.  
  223. #endif // __CFX_H__
  224.  
  225.  
  226.  
  227. // CCFXRequest::AttributeExists //////////////////////////////////////////////////
  228. // 
  229. // @mfunc BOOL | CCFXRequest | AttributeExists | 
  230. //   Checks to see whether the attribute was passed to the tag.
  231. //
  232. // @parm LPCSTR | lpszName | Name of the attribute to check (case insensitive).
  233. //
  234. // @rdesc Returns TRUE if the attribute is available otherwise returns FALSE.
  235. //
  236. // @ex The following example checks to see if the user passed an
  237. //     attribute named DESTINATION to the tag and throws an exception
  238. //     if the attribute was not passed: |
  239. //
  240. //    if ( pRequest->AttributeExists("DESTINATION")==FALSE )
  241. //    {
  242. //        pRequest->ThrowException( 
  243. //            "Missing DESTINATION parameter",
  244. //            "You must pass a DESTINATION parameter in "
  245. //            "order for this tag to work correctly." ) ;   
  246. //    }
  247. //
  248. // @xref <c CCFXRequest> <mf CCFXRequest::GetAttribute> 
  249. //       <mf CCFXRequest::GetAttributeList>
  250.  
  251.  
  252. // CCFXRequest::GetAttribute //////////////////////////////////////////////////
  253. //
  254. // @mfunc LPCSTR | CCFXRequest | GetAttribute | 
  255. //   Retrieves the value of the passed attribute. Returns
  256. //   an empty string if the attribute does not exist (use
  257. //   <mf CCFXRequest::AttributeExists> to test whether an 
  258. //   attribute was passed to the tag).
  259. //
  260. // @parm LPCSTR | lpszName | Name of the attribute to retrieve (case insensitive).
  261. //
  262. // @rdesc The value of the attribute passed to the tag. If no attribute
  263. //        of that name was passed to the tag then an empty string is returned.
  264. //
  265. // @ex The following example retrieves an attribute named DESTINATION 
  266. //     and writes its value back to the user: |
  267. //
  268. //    LPCSTR lpszDestination = pRequest->GetAttribute("DESTINATION") ;
  269. //    pRequest->Write( "The destination is: " ) ;
  270. //    pRequest->Write( lpszDestination ) ;
  271. //
  272. // @xref <c CCFXRequest> <mf CCFXRequest::AttributeExists> 
  273. //       <mf CCFXRequest::GetAttributeList>
  274.  
  275.  
  276. // CCFXRequest::GetAttributeList //////////////////////////////////////////////
  277. //
  278. // @mfunc <c CCFXStringSet>* | CCFXRequest | GetAttributeList | 
  279. //   Retrieves a list of all attribute names passed to the tag. To retrieve
  280. //   the value of an individual attribute you should use the 
  281. //     <mf CCFXRequest::GetAttribute> member function.
  282. //
  283. // @rdesc An object of class <c CCFXStringSet> which contains a
  284. //        list of all attributes passed to the tag.<nl>You are not 
  285. //        responsible for freeing the memory allocated for the
  286. //        returned string set (it will be automatically freed by
  287. //        ColdFusion after the request is completed). 
  288. //
  289. // @ex The following example retrieves the list of attributes and then
  290. //     iterates over the list, writing each attribute and its value
  291. //     back to the user. |
  292. //  
  293. //    LPCSTR lpszName, lpszValue ;        
  294. //    CCFXStringSet* pAttribs = pRequest->GetAttributeList() ;
  295. //    int nNumAttribs = pAttribs->GetCount() ;    
  296. //    
  297. //    for( int i=1; i<=nNumAttribs; i++ )
  298. //    {
  299. //        lpszName = pAttribs->GetString( i ) ;
  300. //        lpszValue = pRequest->GetAttribute( lpszName ) ;
  301. //        pRequest->Write( lpszName ) ;
  302. //        pRequest->Write( " = " ) ;
  303. //        pRequest->Write( lpszValue ) ;
  304. //        pRequest->Write( "<BR>" ) ;
  305. //    }
  306. //
  307. // @xref <c CCFXRequest> <c CCFXStringSet> <mf CCFXRequest::AttributeExists> 
  308. //       <mf CCFXRequest::GetAttribute>
  309.  
  310.  
  311. // CCFXRequest::GetQuery //////////////////////////////////////////////
  312. //
  313. // @mfunc <c CCFXQuery>* | CCFXRequest | GetQuery | 
  314. //   Retrieves the query which was passed to the tag. To pass a query
  315. //   to a custom tag you use the QUERY attribute. This attribute should
  316. //   be set to the name of an existing query (created using the DBQUERY
  317. //   tag or another custom tag). The QUERY attribute is optional and 
  318. //   should only be used by tags which need to process an existing dataset.
  319. //
  320. // @rdesc An object of class <c CCFXQuery> which represents the
  321. //        query which was passed to the tag. If no query was passed
  322. //        to the tag then NULL is returned. <nl>You are not 
  323. //        responsible for freeing the memory allocated for the
  324. //        returned query (it will be automatically freed by
  325. //        ColdFusion after the request is completed). 
  326. //
  327. // @ex The following example retrieves the query which was passed
  328. //       to the tag. If no query was passed then an exception is thrown: |
  329. //  
  330. //    CCFXQuery* pQuery = pRequest->GetQuery() ;
  331. //    if ( pQuery == NULL )
  332. //    {
  333. //        pRequest->ThrowException( 
  334. //            "Missing QUERY parameter",
  335. //            "You must pass a QUERY parameter in "
  336. //            "order for this tag to work correctly." ) ;   
  337. //    }
  338. //
  339. // @xref <c CCFXRequest> <c CCFXQuery> <mf CCFXRequest::AddQuery>
  340.  
  341.  
  342. // CCFXRequest::GetSetting //////////////////////////////////////////////////
  343. //
  344. // @mfunc LPCSTR | CCFXRequest | GetSetting | 
  345. //   Retrieves the value of a global custom tag setting.
  346. //   Custom tag settings are stored within the CustomTags
  347. //   section of the ColdFusion Registry key.
  348. //
  349. // @parm LPCSTR | lpszSettingName | Name of the setting to retrieve (case insensitive).
  350. //
  351. // @rdesc The value of the custom tag setting. If no setting
  352. //        of that name exists then an empty string is returned.
  353. //
  354. // @ex The following example retrieves the value of a setting named 
  355. //     'VerifyAddress' and uses the returned value to determine
  356. //     what actions to take next: |
  357. //
  358. //    LPCSTR lpszVerify = pRequest->GetSetting("VerifyAddress") ;
  359. //    BOOL bVerify = atoi(lpszVerify) ;
  360. //    if ( bVerify == TRUE )
  361. //    {
  362. //        // Do address verification...
  363. //    }
  364. //
  365. // @xref <c CCFXRequest> 
  366.  
  367.  
  368. // CCFXRequest::Write //////////////////////////////////////////////////
  369. //
  370. // @mfunc void | CCFXRequest | Write | 
  371. //   Writes text output back to the user.
  372. //
  373. // @parm LPCSTR | lpszOutput | Text to output.
  374. //
  375. // @ex The following example creates a buffer to hold an output string,
  376. //     fills the buffer with data, and then writes the output 
  377. //     back to the user: |
  378. //
  379. //    CHAR buffOutput[1024] ;
  380. //    wsprintf( buffOutput, "The destination is: %s", 
  381. //              pRequest->GetAttribute("DESTINATION") ) ;
  382. //    pRequest->Write( buffOutput ) ;
  383. //
  384. //
  385. // @xref <c CCFXRequest> 
  386.  
  387.  
  388. // CCFXRequest::SetVariable///////////////////////////////////////////////
  389. //
  390. // @mfunc void | CCFXRequest | SetVariable | 
  391. //   Sets a variable in the calling template. If the 
  392. //   variable name specified already exists in the template then its
  393. //   value is replaced. If it does not already exist then a new variable
  394. //   is created. The values of variables created using SetVariable can
  395. //   be accessed in the same manner as other template variables (e.g. #MessageSent#).
  396. //
  397. // @parm LPCSTR | lpszName | Name of variable.
  398. // @parm LPCSTR | lpszValue | Value of variable.
  399. //
  400. // @ex The following example sets the value of a variable
  401. //     named 'MessageSent' based on the success of an operation
  402. //     performed by the custom tag: |
  403. //    
  404. //    BOOL bMessageSent ;
  405. //
  406. //    ...attempt to send the message...
  407. //
  408. //    if ( bMessageSent == TRUE )
  409. //    {
  410. //        pRequest->SetVariable( "MessageSent", "Yes" ) ;
  411. //    }
  412. //    else
  413. //    {
  414. //        pRequest->SetVariable( "MessageSent", "No" ) ;
  415. //    }
  416. //
  417. // @xref <c CCFXRequest>
  418. //
  419.  
  420.  
  421. // CCFXRequest::AddQuery ///////////////////////////////////////////////
  422. //
  423. // @mfunc <c CCFXQuery>* | CCFXRequest | AddQuery | 
  424. //   
  425. // Adds a query to the calling template. This query can
  426. // then be accessed by DBML tags (e.g. DBOUTPUT or DBTABLE) within the 
  427. // template. Note that after calling AddQuery
  428. // the query exists but is empty (i.e. it has 0 rows). To populate the
  429. // query with data you should call the CCFXQuery member functions
  430. // <mf CCFXQuery::AddRow> and <mf CCFXQuery::SetData>.
  431. //
  432. // @parm LPCSTR | lpszName | Name of query to add to the template (must be unique).
  433. // @parm <c CCFXStringSet>* | pColumns | List of columns names to be used in the query.
  434. //
  435. // @rdesc Returns a pointer to the query which was added to the template (an 
  436. // object of class <c CCFXQuery>). You are not responsible for freeing the 
  437. // memory allocated for the returned query (it will be automatically freed by
  438. // ColdFusion after the request is completed).  
  439. //
  440. // @ex The following example adds a query named 'People' to the calling template.
  441. //     The query has two columns ('FirstName' and 'LastName') and 2 rows: |
  442. //    
  443. //    // Create a string set and add the column names to it
  444. //    CCFXStringSet* pColumns = pRequest->CreateStringSet() ;
  445. //    int iFirstName = pColumns->AddString( "FirstName" ) ;
  446. //    int iLastName = pColumns->AddString( "LastName" ) ;
  447. //
  448. //    // Create a query which contains these columns
  449. //    CCFXQuery* pQuery = pRequest->AddQuery( "People", pColumns ) ;
  450. //                    
  451. //    // Add data to the query
  452. //    int iRow ;
  453. //    iRow = pQuery->AddRow() ;
  454. //    pQuery->SetData( iRow, iFirstName, "John" ) ;
  455. //    pQuery->SetData( iRow, iLastName, "Smith" ) ;
  456. //    iRow = pQuery->AddRow() ;
  457. //    pQuery->SetData( iRow, iFirstName, "Jane" ) ;
  458. //    pQuery->SetData( iRow, iLastName, "Doe" ) ;
  459. //
  460. // @xref <c CCFXRequest> <c CCFXQuery> <mf CCFXRequest::GetQuery>
  461. // <mf CCFXQuery::AddRow> <mf CCFXQuery::SetData>
  462. //
  463.  
  464.  
  465. // CCFXRequest::SetCustomData //////////////////////////////////////////////
  466. //
  467. // @mfunc void | CCFXRequest | SetCustomData | 
  468. //   Sets custom (tag specific) data to carry along with the request. You
  469. //   should use this function to store request specific data which you wish
  470. //   to pass along to procedures within your custom tag implementation.
  471. //
  472. // @parm LPVOID | lpvData | Pointer to custom data
  473. //
  474. // @ex The following example creates a request-specific 
  475. //     data structure of hypothetical type MYTAGDATA and 
  476. //       stores a pointer to the structure in the request for future use: |
  477. //
  478. //    void ProcessTagRequest( CCFXRequest* pRequest ) 
  479. //    {
  480. //        try
  481. //        {
  482. //            MYTAGDATA tagData ;
  483. //            pRequest->SetCustomData( (LPVOID)&tagData ) ;
  484. //            
  485. //        ... remainder of procedure ...
  486. //    }
  487. //
  488. // @xref <c CCFXRequest> <mf CCFXRequest::GetCustomData>
  489.  
  490.  
  491.  
  492. // CCFXRequest::GetCustomData //////////////////////////////////////////////////
  493. // 
  494. // @mfunc LPVOID | CCFXRequest | GetCustomData | 
  495. //   Gets the custom (tag specific) data for the request. This member is 
  496. //   typically used from within subroutines of your tag implementation to
  497. //   extract tag specific data from within the request.
  498. //
  499. // @rdesc Returns a pointer to the custom data or returns NULL if no
  500. //        custom data has been set during this request using 
  501. //        <mf CCFXRequest::SetCustomData>.
  502. //
  503. // @ex The following example retrieves a pointer to a request specific 
  504. //     data structure of hypothetical type MYTAGDATA: |
  505. //
  506. //    void DoSomeGruntWork( CCFXRequest* pRequest ) 
  507. //    {
  508. //        MYTAGDATA* pTagData = 
  509. //            (MYTAGDATA*)pRequest->GetCustomData() ;
  510. //            
  511. //        ... remainder of procedure ...
  512. //    }
  513. //
  514. // @xref <c CCFXRequest> <mf CCFXRequest::SetCustomData> 
  515.  
  516.  
  517.  
  518. // CCFXRequest::Debug //////////////////////////////////////////////////
  519. // 
  520. // @mfunc BOOL | CCFXRequest | Debug | 
  521. //   Checks whether the tag contains the DEBUG attribute. You should use
  522. //   this function to determine whether or not you need to write debug
  523. //   information for this request (see <mf CCFXRequest::WriteDebug> for
  524. //   details on writing debug information).
  525. //
  526. // @rdesc Returns TRUE if the tag contains the DEBUG attribute otherwise
  527. //        returns FALSE.
  528. //
  529. // @ex The following example checks to see whether the DEBUG attribute
  530. //     is present, and if it is then it writes a brief debug message: |
  531. //
  532. //    if ( pRequest->Debug() )
  533. //    {
  534. //        pRequest->WriteDebug( "Top secret debug info" ) ;
  535. //    }
  536. //
  537. // @xref <c CCFXRequest> <mf CCFXRequest::WriteDebug> 
  538.  
  539.  
  540. // CCFXRequest::WriteDebug //////////////////////////////////////////////
  541. //
  542. // @mfunc void | CCFXRequest | WriteDebug | 
  543. //   Writes text output into the debug stream. This text is only displayed
  544. //   to the end-user if the tag contains the DEBUG attribute (see the
  545. //   <mf CCFXRequest::Debug> member function).
  546. //
  547. // @parm LPCSTR | lpszOutput | Text to output.
  548. //
  549. // @ex The following example checks to see whether the DEBUG attribute
  550. //     is present, and if it is then it writes a brief debug message: |
  551. //
  552. //    if ( pRequest->Debug() )
  553. //    {
  554. //        pRequest->WriteDebug( "Top secret debug info" ) ;
  555. //    }
  556. //
  557. // @xref <c CCFXRequest> <mf CFXRequest::Debug>
  558.  
  559.  
  560. // CCFXRequest::CreateStringSet //////////////////////////////////////////
  561. //
  562. // @mfunc <c CCFXStringSet>* | CCFXRequest | CreateStringSet | 
  563. //   Allocates and returns a new CCFXStringSet instance. Note that
  564. //   string sets should always be created using this function as 
  565. //   opposed to directly using the 'new' operator.
  566. //
  567. // @rdesc An object of class <c CCFXStringSet>. You are not 
  568. //        responsible for freeing the memory allocated for the
  569. //        returned string set (it will be automatically freed by
  570. //        ColdFusion after the request is completed). 
  571. //
  572. // @ex The following example creates a string set and adds 3 strings
  573. //     to it: |
  574. //  
  575. //    CCFXStringSet* pColors = pRequest->CreateStringSet() ;
  576. //    pColors->AddString( "Red" ) ;
  577. //    pColors->AddString( "Green" ) ;
  578. //    pColors->AddString( "Blue" ) ;
  579. //
  580. // @xref <c CCFXRequest> <c CCFXStringSet>
  581.  
  582.  
  583. // CCFXRequest::ThrowException ///////////////////////////////////////////
  584. //
  585. // @mfunc void | CCFXRequest | ThrowException | 
  586. //
  587. //  Throws an exception and ends processing of this request. You should
  588. //  call this function when you encounter an error which does not allow
  589. //  you to continue processing the request. Note that this function
  590. //  is almost always combined with the <mf CCFXRequest::ReThrowException>
  591. //  member function to provide protection against resource leaks 
  592. //  in extension code.
  593. //
  594. // @parm LPCSTR | lpszError | Short identifier for error.
  595. // @parm LPCSTR | lpszDiagnostics | Error diagnostic information.
  596. //
  597. // @ex The following example throws an exception indicating that
  598. //     an unexpected error occurred while processing the request: |
  599. //    
  600. //    char buffError[512] ;
  601. //    wsprintf( buffError, 
  602. //        "Unexpected Windows NT error number %ld "
  603. //        "occurred while processing request.", GetLastError() ) ;
  604. //    
  605. //    pRequest->ThrowException( "Error occurred", buffError ) ;
  606. //
  607. // @xref <c CCFXRequest> <c CCFXException> <mf CCFXRequest::ReThrowException>
  608. //
  609.  
  610.  
  611. // CCFXRequest::ReThrowException ///////////////////////////////////////////
  612. //
  613. // @mfunc void | CCFXRequest | ReThrowException | 
  614. //
  615. //  Re-throws an exception which has been caught within an extension
  616. //  procedure. This function is used to avoid having C++ exceptions
  617. //  thrown by DLL extension code propagate back into ColdFusion. You
  618. //  should catch ALL C++ exceptions which occur in your extension code
  619. //  and then either re-throw them (if they are of the CCFXException class)
  620. //  or create and throw a new exception using <mf CCFXRequest::ThrowException>.
  621. //
  622. // @parm <c CCFXException>* | e | An existing CCFXException which has been caught.
  623. //
  624. // @ex The following code demonstrates the correct way to handle 
  625. //     exceptions in ColdFusion Extension DLL procedures: |
  626. //    
  627. //    try
  628. //    {
  629. //
  630. //        ...Code which could throw an exception...
  631. //
  632. //    }
  633. //    catch( CCFXException* e )
  634. //    {
  635. //        ...Do appropriate resource cleanup here...
  636. //        
  637. //        // Re-throw the exception
  638. //        pRequest->ReThrowException( e ) ;
  639. //    }
  640. //    catch( ... )
  641. //    {
  642. //        // Something nasty happened, don't even try
  643. //        // to do resource cleanup
  644. //        
  645. //        pRequest->ThrowException( 
  646. //            "Unexpected error occurred in CFX tag", "" ) ;
  647. //    }
  648. //
  649. // @xref <c CCFXRequest> <c CCFXException> <mf CCFXRequest::ThrowException>
  650.  
  651.  
  652.  
  653. // CCFXQuery::GetName //////////////////////////////////////////////////
  654. //
  655. // @mfunc LPCSTR | CCFXQuery | GetName | 
  656. //   Retrieves the name of the query.
  657. //
  658. // @rdesc The name of the query.
  659. //
  660. // @ex The following example retrieves the name of the query 
  661. //     and writes it back to the user: |
  662. //
  663. //    CCFXQuery* pQuery = pRequest->GetQuery() ;
  664. //    pRequest->Write( "The query name is: " ) ;
  665. //    pRequest->Write( pQuery->GetName() ) ;
  666. //
  667. // @xref <c CCFXQuery> 
  668.  
  669.  
  670. // CCFXQuery::GetRowCount /////////////////////////////////////////////
  671. //
  672. // @mfunc LPCSTR | CCFXQuery | GetRowCount | 
  673. //   Retrieves the number of rows in the query.
  674. //
  675. // @rdesc The number of rows contained in the query.
  676. //
  677. // @ex The following example retrieves the number of rows
  678. //     in a query and writes it back to the user: | 
  679. //
  680. //    CCFXQuery* pQuery = pRequest->GetQuery() ;
  681. //    char buffOutput[256] ;
  682. //    wsprintf( buffOutput, 
  683. //        "The number of rows in the query is %ld.",
  684. //        pQuery->GetRowCount() ) ;
  685. //    pRequest->Write( buffOutput ) ;
  686. //
  687. // @xref <c CCFXQuery> 
  688.  
  689.  
  690. // CCFXQuery::GetColumns //////////////////////////////////////////////
  691. //
  692. // @mfunc <c CCFXStringSet>* | CCFXQuery | GetColumns | 
  693. //   Retrieves a list of the column names contained in the query. 
  694. //
  695. // @rdesc An object of class <c CCFXStringSet> which contains a
  696. //        list of the columns contained in the query. You are not 
  697. //        responsible for freeing the memory allocated for the
  698. //        returned string set (it will be automatically freed by
  699. //        ColdFusion after the request is completed). 
  700. //
  701. // @ex The following example retrieves the list of columns and then
  702. //     iterates over the list, writing each column name back to the user. |
  703. //  
  704. //    // Get the list of columns from the query
  705. //    CCFXStringSet* pColumns = pQuery->GetColumns() ;
  706. //    int nNumColumns = pColumns->GetCount() ;    
  707. //    
  708. //    // Print the list of columns to the user
  709. //    pRequest->Write( "Columns in query: " ) ;
  710. //    for( int i=1; i<=nNumColumns; i++ )
  711. //    {
  712. //        pRequest->Write( pColumns->GetString( i ) ) ;
  713. //        pRequest->Write( " " ) ;
  714. //    }
  715. //
  716. // @xref <c CCFXQuery> <c CCFXStringSet> 
  717. //
  718.  
  719.  
  720. // CCFXQuery::GetData ////////////////////////////////////////////////
  721. //
  722. // @mfunc LPCSTR | CCFXQuery | GetData | 
  723. //   Retrieves a data element from a row and column of the query.
  724. //   Row and column indexes begin with 1. You can determine the 
  725. //   number of rows in the query by calling <mf CCFXQuery::GetRowCount>.
  726. //     You can determine the number of columns in the query by 
  727. //     retrieving the list of columns using <mf CCFXQuery::GetColumns> and
  728. //   then calling <mf CCFXStringSet::GetCount> on the returned 
  729. //   string set.
  730. //
  731. // @parm int | iRow | Row to retrieve data from (1-based).
  732. // @parm int | lColumn | Column to retrieve data from (1-based).
  733. //
  734. // @rdesc The value of the requested data element.
  735. //
  736. // @ex The following example iterates over the elements of a
  737. //     query and writes the data in the query back to
  738. //     the user in a simple, space-delimited format: |
  739. //
  740. //    int iRow, iCol ;
  741. //    int nNumCols = pQuery->GetColumns()->GetCount() ;
  742. //    int nNumRows = pQuery->GetRowCount() ;
  743. //    for ( iRow=1; iRow<=nNumRows; iRow++ )
  744. //    {
  745. //        for ( iCol=1; iCol<=nNumCols; iCol++ )
  746. //        {
  747. //            pRequest->Write( pQuery->GetData( iRow, iCol ) ) ;
  748. //            pRequest->Write( " " ) ;
  749. //        }
  750. //        pRequest->Write( "<BR>" ) ;
  751. //    }
  752. //
  753. // @xref <c CCFXQuery> <c CFXStringSet> <mf CCFXQuery::SetData> 
  754. //
  755.  
  756.  
  757. // CCFXQuery::AddRow /////////////////////////////////////////////////
  758. //
  759. // @mfunc int | CCFXQuery | AddRow |
  760. //   Add a new row to the query. You should call this function each
  761. //   time you want to append a row to the query.
  762. //
  763. // @rdesc The index of the row which was appended to the query.
  764. //
  765. // @ex The following example demonstrates the addition of 2 rows
  766. //     to a query which has 3 columns ('City', 'State', and 'Zip'): |
  767. //
  768. //    // First row
  769. //    int iRow ;
  770. //    iRow = pQuery->AddRow() ;
  771. //    pQuery->SetData( iCity, iRow, "Minneapolis" ) ;
  772. //    pQuery->SetData( iState, iRow, "MN" ) ;
  773. //    pQuery->SetData( iZip, iRow, "55345" ) ;
  774. //
  775. //    // Second row
  776. //    iRow = pQuery->AddRow() ;
  777. //    pQuery->SetData( iCity, iRow, "St. Paul" ) ;
  778. //    pQuery->SetData( iState, iRow, "MN" ) ;
  779. //    pQuery->SetData( iZip, iRow, "55105" ) ;
  780. //    
  781. // @xref <c CCFXQuery> <mf CCFXQuery::SetData>
  782. //
  783.  
  784.  
  785. // CCFXQuery::SetData ////////////////////////////////////////////////
  786. //
  787. // @mfunc void | CCFXQuery | SetData | 
  788. //   Sets a data element within a row and column of the query.
  789. //   Row and column indexes begin with 1. Before calling SetData
  790. //   for a given row you should be sure to call <mf CCFXQuery::AddRow>
  791. //   and use the return value as the row index for your call
  792. //   to SetData.
  793. //
  794. // @parm int | iRow | Row of data element to set (1-based).
  795. // @parm int | lColumn | Column of data element to set (1-based).
  796. // @parm LPCSTR | lpszData | New value for data element.
  797. //
  798. // @ex The following example demonstrates the addition of 2 rows
  799. //     to a query which has 3 columns ('City', 'State', and 'Zip'): |
  800. //
  801. //    // First row
  802. //    int iRow ;
  803. //    iRow = pQuery->AddRow() ;
  804. //    pQuery->SetData( iCity, iRow, "Minneapolis" ) ;
  805. //    pQuery->SetData( iState, iRow, "MN" ) ;
  806. //    pQuery->SetData( iZip, iRow, "55345" ) ;
  807. //
  808. //    // Second row
  809. //    iRow = pQuery->AddRow() ;
  810. //    pQuery->SetData( iCity, iRow, "St. Paul" ) ;
  811. //    pQuery->SetData( iState, iRow, "MN" ) ;
  812. //    pQuery->SetData( iZip, iRow, "55105" ) ;
  813. //    
  814. // @xref <c CCFXQuery> <mf CCFXQuery::AddRow>
  815. //
  816.  
  817. // CCFXQuery::SetQueryString ////////////////////////////////////////////
  818. //
  819. // This call is deprecated.
  820. //
  821. // @mfunc void | CCFXQuery | SetQueryString | 
  822. //   Set the query string which will displayed along with
  823. //   the query debug output. For queries generated by the
  824. //   DBQUERY tag this is the SQL statement. For your
  825. //   custom tag it may be something different, or you may not
  826. //   wish to display a query string at all.
  827. //
  828. // @parm LPCSTR | lpszQuery | Text of query string.
  829. //
  830. // @ex The following example is from a hypothetical custom
  831. //     tag which does directory browsing based on a command
  832. //     string passed to the tag: |
  833. //
  834. //    LPCSTR lpszDirListCommand = 
  835. //        pRequest->GetAttribute("COMMAND") ;
  836. //    
  837. //    ...Create a query (pQuery) and populate it with the
  838. //       contents of the directory listing...
  839. //
  840. //    pQuery->SetQueryString( lpszDirListCommand ) ;
  841. //
  842. // @xref <c CCFXQuery> <mf CCFXQuery::SetTotalTime>
  843. //
  844.  
  845.  
  846. // CCFXQuery::SetTotalTime //////////////////////////////////////////
  847. //
  848. // This call is deprecated.
  849. //
  850. // @mfunc void | CCFXQuery | SetTotalTime | 
  851. //   Set the number of milliseconds which were required to process
  852. //   this query. This number will be displayed along with
  853. //   the query debug output.
  854. //
  855. // @parm DWORD | dwMilliseconds | Execution time in milliseconds.
  856. //
  857. // @ex The following example demonstrates the methodology used
  858. //     to set the total time for a query: |
  859. //
  860. //    DWORD dwStartTime = GetCurrentTime() ;
  861. //
  862. //    ...execute the query and populate it with data...
  863. //
  864. //    pQuery->SetTotalTime( GetCurrentTime() - dwStartTime ) ;
  865. //
  866. // @xref <c CCFXQuery> <mf CCFXQuery::SetQueryString>
  867. //
  868.  
  869.  
  870. // CCFXStringSet::AddString ////////////////////////////////////////
  871. //
  872. // @mfunc int | CCFXStringSet | AddString |
  873. //    Add a string to the end of the list. 
  874. //
  875. // @parm LPCSTR | lpszString | String to add to the list.
  876. //
  877. // @rdesc The index of the string which was added.
  878. //
  879. // @ex The following example demonstrates adding three strings
  880. //     to a string set and saving the indexes of the items 
  881. //     which are added: |
  882. //
  883. //    CCFXStringSet* pSet = pRequest->CreateStringSet() ;
  884. //    int iRed = pSet->AddString( "Red" ) ;
  885. //    int iGreen = pSet->AddString( "Green" ) ;
  886. //    int iBlue = pSet->AddString( "Blue" ) ;
  887. //
  888. // @xref <c CCFXStringSet>
  889. //
  890.  
  891.  
  892. // CCFXStringSet::GetCount ////////////////////////////////////
  893. //
  894. // @mfunc int | CCFXStringSet | GetCount |
  895. //    Get the number of strings contained in the string set. This
  896. //  value can be used along with the <mf CCFXStringSet::GetString>
  897. //  function to iterate over the strings in the set (when iterating,
  898. //  remember that the index values for strings in the list begin at 1).
  899. //
  900. // @rdesc The number of strings contained in the string set.
  901. //
  902. // @ex The following example demonstrates using GetCount along 
  903. //     with GetString to iterate over a string set and write
  904. //     the contents of the list back to the user: |
  905. //
  906. //    int nNumItems = pStringSet->GetCount() ;
  907. //    for ( int i=1; i<=nNumItems; i++ )
  908. //    {
  909. //        pRequest->Write( pStringSet->GetString( i ) ) ;
  910. //        pRequest->Write( "<BR>" ) ;
  911. //    }
  912. //
  913. // @xref <c CCFXStringSet>
  914. //
  915.  
  916.  
  917. // CCFXStringSet::GetIndexForString ////////////////////////////////////
  918. //
  919. // @mfunc int | CCFXStringSet | GetIndexForString |
  920. //    Do a case insensitive search for the passed string. 
  921. //
  922. // @parm LPCSTR | lpszString | String to search for.
  923. //
  924. // @rdesc If the string is found then its index within the
  925. //        string set is returned. If it is not found then
  926. //        the constant CFX_STRING_NOT_FOUND is returned.
  927. //
  928. // @ex The following example illustrates searching for a
  929. //     a string and throwing an exception if it is not 
  930. //     found: |
  931. //
  932. //    CCFXStringSet* pAttribs = pRequest->GetAttributeList() ;
  933. //
  934. //    int iDestination = 
  935. //        pAttribs->GetIndexForString("DESTINATION") ;
  936. //    if ( iDestination == CFX_STRING_NOT_FOUND )
  937. //    {
  938. //        pRequest->ThrowException( 
  939. //            "DESTINATION attribute not found."
  940. //            "The DESTINATION attribute is required "
  941. //            "by this tag." ) ;
  942. //    }
  943. //
  944. // @xref <c CCFXStringSet>
  945. //
  946.  
  947. // CCFXStringSet::GetString ///////////////////////////////////////////
  948. //
  949. // @mfunc LPCSTR | CCFXStringSet | GetString |
  950. //    Retrieve the string located at the passed index (note that
  951. //  index values are 1-based).
  952. //
  953. // @parm int | iIndex | Index of string to retrieve.
  954. //
  955. // @rdesc The string located at the passed index.
  956. //
  957. // @ex The following example demonstrates using GetString along 
  958. //     with GetCount to iterate over a string set and write
  959. //     the contents of the list back to the user: |
  960. //
  961. //    int nNumItems = pStringSet->GetCount() ;
  962. //    for ( int i=1; i<=nNumItems; i++ )
  963. //    {
  964. //        pRequest->Write( pStringSet->GetString( i ) ) ;
  965. //        pRequest->Write( "<BR>" ) ;
  966. //    }
  967. //
  968. // @xref <c CCFXStringSet>
  969. //
  970.  
  971.  
  972.  
  973.     
  974.  
  975.  
  976.  
  977.