CCFXRequest クラス

ColdFusion Extension (CFX) に対して行われるリクエストを表す抽象クラスです。このクラスのインスタンスは、拡張 DLL のメイン関数に渡されます。このクラスではカスタム拡張によって使われるいくつかのインターフェイスが提供されます。このようなインターフェイスには、次の処理を行う関数が含まれます。

クラス メンバ

virtual BOOL AttributeExists( LPCSTR lpszName )

CCFXRequest::AttributeExists により、タグに属性が渡されるかどうかをチェッ クします。

virtual LPCSTR GetAttribute( LPCSTR lpszName )

CCFXRequest::GetAttributeにより、渡された属性の値を取り出します。

virtual CCFXStringSet* GetAttributeList()

CCFXRequest::GetAttributeList により、タグに渡されるすべての属性名のリスト を取り出します。

virtual CCFXQuery* GetQuery()

CCFXRequest::GetQuery により、タグに渡されたクエリを取り出します。

virtual LPCSTR GetSetting( LPCSTR lpszSettingName )

CCFXRequest::GetSettingカスタム タグ設定の値を取り出します。

virtual void Write( LPCSTR lpszOutput )

CCFXRequest::Write により、テキスト出力をユーザに返します。

virtual void SetVariable( LPCSTR lpszName, LPCSTR lpszValue )

CCFXRequest::SetVariableにより、このタグを含むテンプレートに変数を設定し ます。

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

CCFXRequest::AddQuery により、このタグを含むテンプレートにクエリを追加 します。

virtual BOOL Debug()

CCFXRequest::Debug により、タグに DEBUG 属性が含まれているかどうかを チェックします。

virtual void WriteDebug( LPCSTR lpszOutput )

CCFXRequest::WriteDebugにより、デバッグ ストリームにテキスト出力を書き 込みます。

virtual CCFXStringSet* CreateStringSet()

CCFXRequest::CreateStringSet により、CCFXStringSet インスタンスが割り合てら れて返されます。

virtual void ThrowException( LPCSTR lpszError, LPCSTR lpszDiagnostics )

CCFXRequest::ThrowException により、エラーが発生し、このリクエストの処理 を終了します。

virtual void ReThrowException( CCFXException* e )

CCFXRequest::ReThrowException により、すでに見つけたエラーを再び発生し ます。

virtual void SetCustomData( LPVOID lpvData )

CCFXRequest::SetCustomDataにより、カスタム (タグ特有の) データを設定し、 リクエストと共に運びます。

virtual LPVOID GetCustomData()

CCFXRequest::GetCustomDataにより、リクエストに対するカスタム (タグ特有) データを取得します。

CCFXRequest::AddQuery

構文

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

説明

呼び出し側のテンプレートにクエリを追加します。このクエリは、テンプレート内の CFML タグ (CFOUTPUT や、CFTABLE など) を使ってアクセスすることができます。AddQuery を呼び出した後は、クエリが空 (1 行もなし) になります。クエリをデータで満たすには、CCFXQuery::AddRow および CCFXQuery::SetData 関数を呼び出します。

戻り値

テンプレートに追加されたクエリにポインタを返します (クラス CCFXQuery のオブジェクト)。リクエストが完了した後、返された文字列セットのために割り当てられていたメモリが解放されます。

パラメータ

パラメータ
説明
lpszName
テンプレートに追加するクエリの名前 (固有でなければなりません)
pColumns
クエリで使う列の名前のリスト

次の例では、呼び出しテンプレートに People という名前のクエリが追加されます。クエリは、2 列 (FirstName と LastName) と 2 行から構成されています。

// 文字列セットを作成して列名を追加します。
CCFXStringSet* pColumns = pRequest->CreateStringSet() ;
int iFirstName = pColumns->AddString( "FirstName" ) ;
int iLastName = pColumns->AddString( "LastName" ) ;
 
// これらの列を含むクエリを作成します。
CCFXQuery* pQuery = pRequest->AddQuery( "People", pColumns ) ;
 
// データをクエリに追加します。
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)

説明

タグに属性が渡されるかどうかをチェックします。属性が利用可能である場合は TRUE を返します。そうでない場合は FALSE を返します。

パラメータ

パラメータ
説明
lpszName
チェックする属性名 (大文字と小文字の区別はありません)

次の例では、ユーザが DESTINATION という名前の属性をタグに渡した場合に、属性が渡されないとエラーとなるかどうかをチェックしています。

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)

説明

インスタンスを割り当てて返します。文字列セットは、新しい演算子を直接使うのではなく、常にこの関数を使って作成しなければならないことに注意してください。

戻り値

クラス CCFXStringSet クラス のオブジェクトを返します。リクエストが完了した後、返された文字列セットのために割り当てられていたメモリが解放されます。

次の例では、文字列セットを作成し、それに 3 つの文字列を追加しています。

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

CCFXRequest::Debug

構文

BOOL CCFXRequest::Debug(void) 

説明

タグに DEBUG 属性があるかどうかをチェックします。この関数を使ってリクエストにデバッグ情報を書き込むかどうか判断します。詳細は、CCFXRequest::WriteDebugを参照してください。

戻り値

タグに DEBUG 属性があれば TRUE を返します。その属性がなければ FALSE を返します。

次の例では、DEBUG 属性があるかどうかをチェックし、存在する場合は簡単なデバッグ メッセージが出力されます。

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

CCFXRequest::GetAttribute

構文

LPCSTR CCFXRequest::GetAttribute(LPCSTR lpszName)

説明

渡された属性の値を取り出します。属性がない場合は、空の文字列を返します (タグに属性が渡されたかどうかをテストするには、CCFXRequest::AttributeExists を使います)。

戻り値

タグに渡された属性の値を返します。その名前の属性がタグに渡されていない場合は、空の文字列が返されます。

パラメータ

パラメータ
説明
lpszName
取り出す属性の名前 (大文字と小文字の区別はありません)

次の例では、DESTINATION という名前の属性を取り出して、その値をユーザに返しています。

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

CCFXRequest::GetAttributeList

構文

CCFXStringSet* CCFXRequest::GetAttributeList(void)

説明

タグに渡されるすべての属性名のリストを取り出します。1 つの属性の値を取り出すには、CCFXRequest::GetAttributeを使います。

戻り値

タグに渡された属性のリストを持つ、クラス CCFXStringSet クラス のオブジェクトを返します。リクエストが完了した後、返された文字列セットのために割り当てられていたメモリが解放されます。

次の例では、属性のリストを取り出した後、繰り返し各属性とその値をユーザに返しています。

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)

説明

リクエストに対するカスタム (タグ特有の) データを取得します。通常、実装したタグのサブルーチン内からこのメンバを使うと、リクエストの中からタグ特有のデータを抽出することができます。

戻り値

カスタムを指すポインタを返すか、リクエスト時に、CCFXRequest::SetCustomData を使って設定されたカスタムデータがないと、NULL を返します。

次の例では、MYTAGDATA という、リクエストに特有のデータ連想配列タイプがあると想定し、それを指すポインタを取り出します。

void DoSomeGruntWork( CCFXRequest* pRequest )
{
    MYTAGDATA* pTagData =
      (MYTAGDATA*)pRequest->GetCustomData() ;
 
    ... remainder of procedure ...
}

CCFXRequest::GetQuery

構文

CCFXQuery* CCFXRequest::GetQuery(void)

説明

タグに渡されたクエリを取り出します。カスタム タグにクエリを渡すには、QUERY 属性を使います。この属性は、既存のクエリの名前に設定しなければなりません (CFQUERY タグまたは別のカスタム タグを使って作成されます)。QUERY 属性は、オプションであり、既存のデータ セットを処理する必要のあるタグの場合のみ使います。

戻り値

タグに渡されたクエリを表す、クラス CCFXQuery クラス のオブジェクトを返します。タグにクエリが渡されていない場合は NULL が返されます。リクエストが完了した後、返された文字列セットのために割り当てられていたメモリが解放されます。

次の例では、タグに渡されたクエリを取り出しています。クエリが渡されていない場合はエラーとなります。

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)

説明

グローバル カスタム タグ設定の値を取り出します。カスタム タグ設定は、
ColdFusion Registry キーの CustomTags セクションに格納されています。

戻り値

カスタム タグ設定の値を返します。その名前の設定値がすでに存在しない場合、空の文字列が返されます。

パラメータ

パラメータ
説明
lpszSettingName
取り出す設定の名前 (大文字と小文字の区別はありません)

次の例では、VerifyAddress という名前の設定の値を取り出し、戻り値を使って、次のアクションを決めています。

LPCSTR lpszVerify = pRequest->GetSetting("VerifyAddress") ;
BOOL bVerify = atoi(lpszVerify) ;
if ( bVerify == TRUE )
{
    // アドレスを検証します。
}

CCFXRequest::ReThrowException

構文

void CCFXRequest::ReThrowException(CCFXException* e)

説明

拡張プロシージャで発生したエラーを再び返します。これは、DLL 拡張コードによって発生した C++ エラーが ColdFusion まで伝播しないようにするための関数です。拡張コードで発生するすべての C++ エラーを検出して再び返すか (CCFXException クラス クラスの場合)、あるいはCCFXRequest::ThrowException を使って新しいエラーを生成して返します。

パラメータ

パラメータ
説明
e
検出された CCFXException エラー

次のコードは、ColdFusion Extension DLL プロシージャでの正しい例外処理方法を示しています。

try
{
          ...Code that could throw an exception...
}
catch( CCFXException* e )
{
          ...Do appropriate resource cleanup here...
          // エラーを再び返します。
          pRequest->ReThrowException( e ) ;
}
catch( ... )
{
          // 重大なエラーが発生しました。
 
          pRequest->ThrowException(
          "Unexpected error occurred in CFX tag", "" ) ;
}

CCFXRequest::SetCustomData

構文

void CCFXRequest::SetCustomData(LPVOID lpvData)

説明

カスタム (タグ特有の) データを設定し、リクエストと共に運びます。この関数を使い、カスタム タグ内のプロシージャと共に渡す、リクエストに特有のデータを格納します。

パラメータ

パラメータ
説明
lpvData
カスタム データを指すポインタ

次の例では、MYTAGDATA という、リクエストに特有のデータ連想配列タイプを作成し、後で使うためにそのリクエスト内の連想配列を指すポインタを格納しています。

id ProcessTagRequest( CCFXRequest* pRequest )
    try
    {
          MYTAGDATA tagData ;
          pRequest->SetCustomData( (LPVOID)&tagData ) ;
 
          ... remainder of procedure ...
}

CCFXRequest::SetVariable

構文

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

説明

呼び出し側テンプレートに変数を設定します。テンプレートに、指定した変数名がすでに存在していると、その値は変更されます。既存の変数がない場合は、新しい変数が作成されます。SetVariable を使って作成された変数の値は、他のテンプレート変数 (#MessageSent# など) と同じ方法でアクセスすることができます。

パラメータ

パラメータ
説明
lpszName
変数の名前
lpszValue
変数の値

次の例では、カスタム タグによって実行された操作の成功に基づいて、MessageSent という名前の変数値が設定されます。

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)

説明

エラーを生成して、このリクエストの処理を終了します。リクエスト処理の継続を許さないエラーが発生した場合は、この関数を呼び出します。この関数は、ほとんどの場合、拡張コードのリソース リークを防ぐために、CCFXRequest::ReThrowException メンバ関数と組み合わせて使われます。

パラメータ

パラメータ
説明
lpszError
エラーのための短い識別子
lpszDiagnostics
エラー診断情報

次の例では、リクエスト処理中に、予測しないエラーが起きたことを示すエラーを返しています。

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)

説明

テキスト出力をユーザに返します。

パラメータ

パラメータ
説明
lpszOutput
出力するテキスト

次の例では、出力文字列を保持するバッファを作成し、バッファをデータで満たし、ユーザにその出力文字列を返しています。

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

CCFXRequest::WriteDebug

構文

void CCFXRequest::WriteDebug(LPCSTR lpszOutput)

説明

デバッグ ストリームにテキスト出力を書き込みます。タグに DEBUG 属性がある場合、このテキストは、エンド ユーザに対してのみ表示されます (詳細については、CCFXRequest::Debugを参照してください)。

パラメータ

パラメータ
説明
lpszOutput
出力するテキスト

次の例では、DEBUG 属性があるかどうかをチェックし、存在する場合は簡単なデバッグ メッセージが出力されます。

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