撰寫 API 程式的一般程序

撰寫 Caching Proxy 外掛程式之前，您需要瞭解 Proxy 伺服器如何運作。Proxy 伺服器的行為可以分割成數個不同的處理程序步驟。對於每一個步驟，您可以提供使用 API 的自訂函數。例如，在讀取用戶端要求之後、執行任何其他處理程序之前，您想要執行任何動作嗎？或者，您可能想在鑑別期間，以及在所要求的檔案傳送之後，執行特殊常式。

預先定義的函數庫會隨 API 提供。外掛程式可以呼叫預先定義的 API 函數，以便與 Proxy 伺服器處理程序互動（例如，操作要求、讀取或寫入要求標頭，或寫入 Proxy 伺服器的日誌）。這些函數不應該與您撰寫的外掛程式函數混淆，後者是由 Proxy 伺服器呼叫。預先定義的函數和巨集說明預先定義的函數。

您要使用伺服器配置檔中對應的 Caching Proxy API 指引，來指示 Proxy 伺服器在適當的步驟呼叫外掛程式函數。 API 步驟的 Caching Proxy 配置指引說明這些指引。

本文件包括下列各項：

可自訂的 Caching Proxy 步驟的基本說明（請參閱伺服器處理程序步驟）
撰寫外掛程式的準則（請參閱準則）
自訂函數（您可對伺服器執行的每一個步驟撰寫它）的原型及其回覆碼（請參閱外掛程式函數原型）
預先定義的函數和巨集（您可以從外掛程式內呼叫它們）的定義及其回覆碼（請參閱預先定義的函數和巨集）
Caching Proxy API 配置指引（請參閱API 步驟的 Caching Proxy 配置指引）

您可以使用這些元件和程序來撰寫自己的 Caching Proxy 外掛程式。

伺服器處理程序步驟

Proxy 伺服器的基本作業可根據伺服器在該階段期間執行的處理類型，而分成幾個步驟。每一個步驟包括程式的指定部分可以執行的接合。藉由將 API 指引新增至 Caching Proxy 配置檔 (ibmproxy.conf)，您可以指出在特定步驟期間要呼叫哪個外掛程式函數。您可以在特定處理程序步驟期間併入該步驟的多個指引，來呼叫數個外掛程式函數。

有些步驟是伺服器要求處理程序的一部分。換句話說，每次 Proxy 伺服器處理要求時都會執行這些步驟。其他步驟的執行與要求處理程序無關；也就是說，不論是否正在處理要求，伺服器都會執行這些步驟。

已編譯的程式位於共用物件（例如，DLL 或 .so 檔案）中，依作業系統而定。當伺服器繼續進行其要求處理程序步驟時，它會呼叫與每一個步驟相關聯的外掛程式函數，直到其中一個函數指出它已處理該要求為止。如果您對某特定步驟指定多個外掛程式函數，則會依函數出現在配置檔中的指引順序來呼叫它們。

如果外掛程式函數未處理該要求（可能是您未併入該步驟的 Caching Proxy API 指引，或該步驟的外掛程式函數傳回 HTTP_NOACTION），伺服器會對該步驟執行其預設動作。

附註：除了 Service 步驟之外，所有步驟都是如此；Service 步驟沒有預設動作。

圖 1描述 Proxy 伺服器處理程序的步驟，並定義與要求處理程序相關之步驟的處理順序。

圖 1. Proxy 伺服器處理程序的步驟流程圖

圖表上四個步驟的執行，與任何用戶端要求的處理無關。這些步驟與 Proxy 伺服器的執行和維護相關。它們包括下列各項：

伺服器起始設定
午夜
GC Advisor
伺服器終止

下列清單說明圖 1圖片中每一個步驟的目的。請注意，不保證會針對特定要求呼叫所有步驟。

伺服器起始設定

當 Proxy 伺服器啟動時及接受任何用戶端要求之前，會執行起始設定。

午夜

在沒有要求環境定義之下，會於午夜執行外掛程式。這個步驟會在圖表中單獨顯示，因為它不是要求處理程序的一部分；換句話說，它的執行與任何要求無關。

GC Advisor

會影響快取檔案的記憶體回收決策。這個步驟會在圖表中單獨顯示，因為它不是要求處理程序的一部分；換句話說，它的執行與任何要求無關。當快取記憶體大小達到最大值時，會執行記憶體回收。（WebSphere® Application Server Caching Proxy 管理手冊 包含配置快取記憶體回收的相關資訊。）

PreExit

會在讀取要求之後、執行任何其他動作之前執行處理。

如果此步驟傳回已處理要求的指示 (HTTP_OK)，則伺服器會略過要求處理程序中的其他步驟，只執行 Transmogrifier、Log 和 PostExit 步驟。

名稱轉換

將虛擬路徑（從 URL）轉換成實體路徑。

授權

會使用儲存的安全記號來檢查保護的實體路徑、ACL 和其他存取控制，並產生基本鑑別 (BA) 所需要的 WWW 鑑別標頭。如果您撰寫自己的外掛程式函數來取代此步驟，則必須自行產生這些標頭。

如需相關資訊，請參閱鑑別和授權。

鑑別

解碼、驗證及儲存安全記號。

如需相關資訊，請參閱鑑別和授權。

Object Type

尋找路徑指示的檔案系統物件。

授權後

會在授權及尋找物件之後、滿足要求之前執行處理。

如果此步驟傳回已處理要求的指示 (HTTP_OK)，則伺服器會略過要求處理程序中的其他步驟，只執行 Transmogrifier、Log 和 PostExit 步驟。

服務

滿足要求（藉由傳送檔案、執行 CGI 等）。

Proxy 顧問

影響 Proxy 和快取決策。

Transmogrifier

針對傳送到用戶端回應的資料部分提供寫入權。

日誌

啟用自訂的交易記載。

錯誤

啟用自訂的錯誤狀況回應。

PostExit

清除配置給要求處理程序的資源。

伺服器終止

當發生正常關機時，會執行清除處理。

準則

遵循為伺服器的外掛程式函數提供的語法和準則，來撰寫程式。提供唯一的函數名稱給每一個外掛程式函數，並視需要呼叫伺服器的預先定義函數。
在 AIX® 系統上，您需要列出外掛程式函數的匯出檔（例如，libmyapp.exp），且您必須鏈結 Caching Proxy API 匯入檔 libhttpdapi.exp。

在 Linux、HP-UX 和 Solaris 系統上，您必須鏈結 libhttpdapi 和 libc 程式庫。

在 Windows 系統上，您需要列出外掛程式函數的模組定義檔 (.def)，且您必須鏈結 HTTPDAPI.LIB。

請務必在函數定義中併入 HTAPI.h 及使用 HTTPD_LINKAGE 巨集。此巨集確保所有函數都使用相同的呼叫慣例。
伺服器是在多執行緒環境中執行；因此，您的外掛程式必須考量執行緒安全。如果應用程式重新進入，效能也不會降低。
使外掛程式中的動作保持在執行緒範圍內。請勿執行處理程序範圍中的任何動作，例如：結束、變更使用者 ID，或登錄信號處理程式。
請勿使用廣域變數，如果您必須使用它們，請以互斥號誌保護廣域變數。
如果您使用 HTTPD_write() 函數將資料傳回到用戶端，請記得設定 Content-Type 標頭。
一律檢查回覆碼，並在必要時提供條件式處理。
編譯及鏈結程式，參照您編譯器的文件，並視作業系統所需來建置共用物件（例如：DLL 或 .so 檔案）。
使用下列編譯及鏈結指令作為準則。
- AIX，使用 IBM® CSet++
  - 編譯：
```
cc_r  -c -qdbxextra -qcpluscmt foo.c
```
  - 鏈結：
```
cc_r -bM:SRE -bnoentry -o libfoo.so foo.o -bI:libhttpdapi.exp 
     -bE:foo.exp
```
    （此指令顯示成兩行，只是為了可讀性。）
- HP-UX，使用 HP C/ANSI C 開發者的軟體組和 HP aC++ 編譯器
  - 編譯：
```
cc -Ae -c +Z +DAportable
```
  - 鏈結：
```
aCC +Z -mt -c +DAportable
```
- Linux，使用 Gnu 編譯器 C (GCC) 3.2.X 版
  - 編譯：
```
gcc -c foo.c
```
  - 鏈結：
```
ld -G -Bsymbolic -o libfoo.so foo.o -lhttpdapi -lc
```
- Solaris，使用 Sun Workshop
  - 編譯：
```
cc -mt -Bsymbolic -c foo.c
```
  - 鏈結：
```
cc -mt -Bsymbolic -G -o libfoo.so foo.o -lhttpdapi -lc
```
- Windows，使用 Microsoft Visual C++
  - 編譯：
```
cl /c /MD /DWIN32 foo.c
```
  - 鏈結：
```
link httpdapi.lib foo.obj /def:foo.def /out:foo.dll /dll 
```
如果要指定匯出，請使用下列其中一種方法：
- 在原始檔中新增 _declspec(dllexport) 定義。
- 在 LIB 指令行上指定 /EXPORT:entryname。
- 建立含有 EXPORTS 陳述式的模組定義檔。
將 Caching Proxy API 指引新增至配置檔，使程式的外掛程式函數與適當步驟產生關聯。在伺服器要求處理程序中，每一個步驟都有個別指引。停止並重新啟動伺服器，使新指引生效。

註：

即使重新啟動，Caching Proxy 也不會卸載共用物件（DLL 或 .so 檔案）。您必須停止後再啟動伺服器，才能釋放共用物件。
在正式作業環境使用您的程式之前，請先嚴格地測試該程式。因為 Caching Proxy 是執行緒伺服器，您必須套用比分出伺服器所需更嚴格的測試。程式中的錯誤會導致 Proxy 伺服器失敗，因為 Proxy 伺服器會直接呼叫程式，且兩者會在相同的程序空間中執行。

外掛程式函數

遵循外掛程式函數原型中呈現的語法，對已定義的要求處理程序步驟撰寫您自己的程式函數。

每一個函數必須以指出所採取動作的值，來填寫回覆碼參數：

回覆碼 HTTP_NOACTION（0 值）表示未採取相關動作。若傳回此回覆碼，則 Proxy 伺服器會對此步驟採取其預設動作。
其中一個有效的 HTTP 回覆碼指出該外掛程式函數處理該步驟。（如需有效回覆碼的清單，請參閱 HTTP 回覆碼和值。）如果提供有效的 HTTP 回覆碼，就不會呼叫其他外掛程式函數，來處理要求中的該步驟。

外掛程式函數原型

每一個 Caching Proxy 步驟的函數原型顯示要使用的格式，並說明它們可執行的處理類型。請注意，函數名稱未預先定義。您必須提供唯一名稱給函數，且可以選擇自己的命名慣例。為了簡化關聯，本文件使用與伺服器處理程序步驟相關的名稱。

在每一個外掛程式函數中，某些預先定義的 API 函數是有效的。有些預先定義的函數並非對所有步驟都有效。當從所有這些外掛程式函數呼叫時，下列預先定義的 API 函數是有效的：

HTTPD_set
HTTPD_extract
httpd_setvar
httpd_getvar
HTTPD_log* 函數

其他有效或無效 API 函數則記錄在函數原型說明中。

傳送至函數的 handle 參數值，可當成第一個引數傳遞至預先定義的函數。預先定義的函數和巨集說明預先定義的 API 函數。

伺服器起始設定

void HTTPD_LINKAGE ServerInitFunction (
     unsigned char *handle, 
     unsigned long *major_version,
     unsigned long *minor_version, 
     long *return_code
     )

在伺服器起始設定期間載入模組之後，會呼叫對此步驟定義的函數。您可在接受任何要求之前，執行起始設定。

雖然會呼叫所有伺服器的起始設定函數，但此步驟中某函數的錯誤回覆碼，卻導致伺服器忽略與傳回錯誤碼的函數配置在相同模組中的所有其他函數。（也就是說，不會呼叫包含在與傳回錯誤的那個函數相同的共用物件中的任何其他函數。）

version 參數包含 Proxy 伺服器的版本號碼；這些是由 Caching Proxy 提供。

PreExit

void  HTTPD_LINKAGE  PreExitFunction (
         unsigned char *handle, 
         long *return_code
         )

在讀取要求之後、發生任何處理之前，會對每一個要求呼叫對此步驟定義的函數。在 Caching Proxy 處理用戶端的要求之前，可利用此步驟的外掛程式來存取該用戶端的要求。

preExit 函數的有效回覆碼如下所示：

0 (HTTP_NOACTION)
200 (HTTP_OK)
4xx 或 5xx 系列中的 HTTP 錯誤（例如，404, HTTP_NOT_FOUND）

不得使用其他回覆碼。

如果此函數傳回 HTTP_OK，Proxy 伺服器會假設已處理該要求。會略過所有後續的要求處理程序步驟，只執行回應步驟（Transmogrifier、Log 和 PostExit）。

在此步驟期間，所有預先定義的 API 函數都有效。

午夜

void  HTTPD_LINKAGE  MidnightFunction (
         unsigned char *handle, 
         long *return_code
         )

會在每天午夜執行對此步驟定義的函數，且不包含要求環境定義。例如，它可用來呼叫子處理程序來分析日誌。（請注意，在此步驟期間，延伸處理可能會干擾記載。）

鑑別

void  HTTPD_LINKAGE  AuthenticationFunction (
         unsigned char *handle, 
         long *return_code
         )

根據要求的鑑別方法，會對每一個要求呼叫對此步驟定義的函數。此函數可用來自訂隨要求傳送的安全記號驗證。

名稱轉換

void  HTTPD_LINKAGE  NameTransFunction (
         unsigned char *handle, 
         long *return_code
         )

會對每一個要求呼叫對此步驟定義的函數。如果您只想對符合某 URL 範本的要求呼叫外掛程式函數，可在配置檔指引中指定該範本。 Name Translation 步驟會發生在處理要求之前，並提供將 URL 對映到物件（例如：檔名）的機制。

授權

void  HTTPD_LINKAGE  AuthorizationFunction (
         unsigned char *handle, 
         long *return_code
         )

會對每一個要求呼叫對此步驟定義的函數。如果您只想對符合某 URL 範本的要求呼叫外掛程式函數，可在配置檔指引中指定該範本。 Authorization 步驟會發生在處理要求之前，並可用來驗證所識別的物件是否能傳回至用戶端。如果您要執行基本鑑別 (BA)，則必須產生所需要的 WWW 鑑別標頭。

Object Type

void  HTTPD_LINKAGE  ObjTypeFunction (
         unsigned char *handle, 
         long *return_code
         )

會對每一個要求呼叫對此步驟定義的函數。如果您只想對符合某 URL 範本的要求呼叫外掛程式函數，可在配置檔指引中指定該範本。 Object Type 步驟會發生在處理要求之前，並可用來檢查物件是否存在，以及執行物件分類。

PostAuthorization

void  HTTPD_LINKAGE  PostAuthFunction (
         unsigned char *handle, 
         long *return_code
         )

在授權要求之後、發生任何處理之前，會呼叫對此步驟定義的函數。如果此函數傳回 HTTP_OK，Proxy 伺服器會假設已處理該要求。會略過所有後續的要求步驟，只執行回應步驟（Transmogrifier、Log 和 PostExit）。

在此步驟期間，所有伺服器預先定義的函數都有效。

服務

void  HTTPD_LINKAGE  ServiceFunction (
         unsigned char *handle, 
         long *return_code 
         )

會對每一個要求呼叫對此步驟定義的函數。如果您只想對符合某 URL 範本的要求呼叫外掛程式函數，可在配置檔指引中指定該範本。若在 PreExit 或 PostAuthorization 步驟中未能滿足該要求，則 Service 步驟可以滿足。

在此步驟期間，所有伺服器預先定義的函數都有效。

如需根據 HTTP 方法而非根據 URL 來配置要執行的「服務」函數相關資訊，請參閱 WebSphere Application Server Caching Proxy 管理手冊 中的「啟用」指引。

Transmogrifier

在此處理程序步驟中呼叫的函數可用來將回應資料過濾為串流。會依序呼叫此步驟的四個外掛程式函數，且每一個函數是作為資料流經的一個管道區段。也就是說，會針對每一個回應，依該順序呼叫您提供的 open、write、close 及 error 函數。每一個函數會輪流處理相同的資料串流。

對於此步驟，您必須實作下列四個函數。（函數名稱不需要符合這些名稱。）

Open
```
void *  HTTPD_LINKAGE  openFunction (
         unsigned char *handle, 
         long *return_code
         )
```
open 函數會執行任何所需的起始設定（例如：緩衝區配置），來處理此串流的資料。 HTTP_OK 以外的任何回覆碼會使此過濾器中斷（不呼叫 write 和 close 函數）。您的函數可傳回空指標，以便您配置結構的空間，並以後續函數的 correlator 參數形式，將指標傳回給您。
Write
```
void  HTTPD_LINKAGE  writeFunction (
         unsigned char *handle, 
         unsigned char *data,    /* 回應資料，由
                                    原始伺服器傳送 */
         unsigned long *length,  /* 回應資料的長度 */
         void *correlator,       /* 由
                                    'open' 函數傳回的指標 */
         long *return_code
         )
```
write 函數處理資料，並可使用新的或變更的資料呼叫伺服器預先定義的 HTTPD_write() 函數。外掛程式不得嘗試釋放傳遞給它的緩衝區，或預期伺服器會釋放它接收的緩衝區。

如果您決定不要在 write 函數的範圍內變更資料，您仍然必須在 open、write 或 close 函數的範圍內呼叫 HTTPD_write() 函數，才能將回應的資料傳遞給用戶端。 correlator 引數是 open 常式中傳回之資料緩衝區的指標。
Close
```
void  HTTPD_LINKAGE  closeFunction (
         unsigned char *handle, 
         void *correlator, 
         long *return_code
         )
```
close 函數會執行任何所需的清除動作（例如：清除及釋放相關性因子緩衝區），來完成處理此串流的資料。correlator 引數是 open 常式中傳回之資料緩衝區的指標。
錯誤
```
void  HTTPD_LINKAGE  errorFunction (
         unsigned char *handle, 
         void *correlator,
         long *return_code
         )
```
error 函數會在傳送錯誤頁面之前執行清除動作，例如：清除或釋放緩衝資料（或兩者）。此時，會呼叫 open、write 及 close 函數來處理錯誤頁面。 correlator 引數是 open 常式中傳回之資料緩衝區的指標。

附註：

撰寫 Transmogrifier 步驟的外掛程式時，您必須在某個時間，在 open、write 和 close 函數範圍內，呼叫 HTTPD_open()、HTTPD_write() 及 HTTPD_close()。 HTTPD_write() 只能在呼叫 HTTPD_open() 函數之後呼叫。這些預先定義的函數，其用途是要提供伺服器的控制，以呼叫順序中的下一個函數。
呼叫 HTTPD_* 函數是 Transmogrifier API 步驟及伺服器要正確執行所必要的。比方說，如果未呼叫 HTTPD_open() 和 HTTPD_close()，標頭不會傳回到用戶端。
請注意，如果在過濾資料串流時未適當選取資料過濾應用程式，可能會發生不想要的結果。如果未正確過濾，CGI 可能無法運作、GIF 檔可能無法顯示，且其他二進位串流可能無法如預期運作。
外掛程式不需要緩衝內容主體。Caching Proxy 會自動決定內容長度。
當您準備將標頭的控制權交給伺服器時，可呼叫 HTTPD_open()。不過，如果您稍後需要在 API 程式中設定標頭，則可先讓 write 或 close 函數呼叫 HTTPD_open() 函數。

註：

您必須在呼叫 HTTPD_open() 函數之前，使用 HTTPD_set() 或 httpd_setvar() 設定任何標頭。
資料串流不包括標頭。外掛程式必須使用 set 和 extract 函數來操作標頭。要等讀取所有標頭之後，才會呼叫外掛程式的 open 函數。
您可以使用多個轉換器 (transmogrifier) 外掛程式，這些外掛程式會依出現在配置檔中的順序來呼叫。
SSL 通道作業未通過轉換器 (transmogrifier) 外掛程式。

GC Advisor

void  HTTPD_LINKAGE  GCAdvisorFunction (
         unsigned char *handle, 
         long *return_code
         )

在記憶體回收期間，會對快取中的每一個檔案呼叫對此步驟定義的函數。此函數可讓您決定要保留和要捨棄的檔案。如需相關資訊，請參閱 GC_* 變數。

Proxy 顧問

void  HTTPD_LINKAGE  ProxyAdvisorFunction (
         unsigned char *handle, 
         long *return_code
         )

在每一個 Proxy 要求的服務期間，會呼叫對此步驟定義的函數。例如，它可用來設定 USE_PROXY 變數。

日誌

void  HTTPD_LINKAGE  LogFunction (
         unsigned char *handle,
         long *return_code
         )

在處理要求及關閉用戶端的通訊之後，會對每一個要求呼叫對此步驟定義的函數。如果您只想對符合某 URL 範本的要求呼叫外掛程式函數，可在配置檔指引中指定該範本。不論要求處理程序成功或失敗，都會呼叫此函數。如果您不想要日誌外掛程式置換預設日誌機制，請將回覆碼設定為 HTTP_NOACTION 而非 HTTP_OK。

錯誤

void  HTTPD_LINKAGE  ErrorFunction (
         unsigned char *handle, 
         long *return_code
         )

會對每一個失敗的要求呼叫對此步驟定義的函數。如果您只想對符合某 URL 範本的失敗要求呼叫外掛程式函數，可在配置檔指引中指定該範本。您可在 Error 步驟中自訂錯誤回應。

PostExit

void  HTTPD_LINKAGE  PostExitFunction (
         unsigned char *handle, 
         long *return_code
         )

不論要求成功或失敗，都會對每一個要求呼叫對此步驟定義的函數。此步驟可讓您對外掛程式配置來處理該要求的任何資源，執行清除作業。

伺服器終止

void  HTTPD_LINKAGE  ServerTermFunction (
         unsigned char *handle, 
         long *return_code
         )

在發生伺服器正常關機時，會呼叫對此步驟定義的函數。它可讓您清除在「伺服器起始設定」步驟期間配置的資源。請勿在此步驟呼叫任何 HTTP_* 函數（其結果無法預期）。如果配置檔中有「伺服器終止」的多個 Caching Proxy API 指引，則全部都會呼叫。

註：

由於 Solaris 程式碼的現行限制，當使用 ibmproxy -stop 指令在 Solaris 平台上關閉 Caching Proxy 時，不會執行「伺服器終止」外掛程式步驟。如需啟動及停止 Caching Proxy 的相關資訊，請參閱 WebSphere Application Server Caching Proxy 管理手冊。

HTTP 回覆碼和值

這些回覆碼遵循全球資訊網協會 (www.w3.org/pub/WWW/Protocols/) 已發佈的 HTTP 1.1 規格 RFC 2616。外掛程式函數必須傳回其中一值。

表 2. Caching Proxy API 函數的 HTTP 回覆碼
值	回覆碼
0	HTTP_NOACTION
100	HTTP_CONTINUE
101	HTTP_SWITCHING_PROTOCOLS
200	HTTP_OK
201	HTTP_CREATED
202	HTTP_ACCEPTED
203	HTTP_NON_AUTHORITATIVE
204	HTTP_NO_CONTENT
205	HTTP_RESET_CONTENT
206	HTTP_PARTIAL_CONTENT
300	HTTP_MULTIPLE_CHOICES
301	HTTP_MOVED_PERMANENTLY
302	HTTP_MOVED_TEMPORARILY
302	HTTP_FOUND
303	HTTP_SEE_OTHER
304	HTTP_NOT_MODIFIED
305	HTTP_USE_PROXY
307	HTTP_TEMPORARY_REDIRECT
400	HTTP_BAD_REQUEST
401	HTTP_UNAUTHORIZED
403	HTTP_FORBIDDEN
404	HTTP_NOT_FOUND
405	HTTP_METHOD_NOT_ALLOWED
406	HTTP_NOT_ACCEPTABLE
407	HTTP_PROXY_UNAUTHORIZED
408	HTTP_REQUEST_TIMEOUT
409	HTTP_CONFLICT
410	HTTP_GONE
411	HTTP_LENGTH_REQUIRED
412	HTTP_PRECONDITION_FAILED
413	HTTP_ENTITY_TOO_LARGE
414	HTTP_URI_TOO_LONG
415	HTTP_BAD_MEDIA_TYPE
416	HTTP_BAD_RANGE
417	HTTP_EXPECTATION_FAILED
500	HTTP_SERVER_ERROR
501	HTTP_NOT_IMPLEMENTED
502	HTTP_BAD_GATEWAY
503	HTTP_SERVICE_UNAVAILABLE
504	HTTP_GATEWAY_TIMEOUT
505	HTTP_BAD_VERSION

預先定義的函數和巨集

您可以從自己的外掛程式函數中，呼叫伺服器預先定義的函數和巨集。您必須使用其預先定義的名稱並遵循下述格式。在參數說明中，字母 i 指輸入參數，字母 o 指輸出參數，i/o 指一個參數同時用於輸入及輸出。

每一個函數會視要求成功與否，傳回其中一個 HTTPD 回覆碼。來自預先定義的函數和巨集的回覆碼說明這些程式碼。

在呼叫這些函數時，請使用提供給外掛程式的 handle 作為第一個參數。否則，函數會傳回 HTTPD_PARAMETER_ERROR 錯誤碼。不接受 NULL 為有效 handle。

HTTPD_authenticate()

鑑別使用者 ID、密碼或兩者。只在 PreExit、Authentication、Authorization 及 PostAuthorization 步驟中有效。

void  HTTPD_LINKAGE  HTTPD_authenticate (
         unsigned char *handle,      /* i; handle */
         long *return_code           /* o; 回覆碼 */
         )

HTTPD_cacheable_url()

根據 Caching Proxy 的標準，回覆指定的 URL 內容是否可以快取。

void HTTPD_LINKAGE  HTTPD_cacheable_url ( 
        unsigned char *handle,      /* i; handle */
        unsigned char *url,         /* i; 要檢查的 URL */
        unsigned char *req_method,  /* i; URL 的要求方法 */
        long *retval                /* o; 回覆碼 */
        )

回覆值 HTTPD_SUCCESS 指 URL 內容可以快取；HTTPD_FAILURE 指內容不可以快取。 HTTPD_INTERNAL_ERROR 也是此函數的可能回覆碼。

HTTPD_close()

（只在 Transmogrifier 步驟中有效。）將控制權轉交給串流堆疊中的下一個 close 常式。在執行任何所要的處理之後，請從 Transmogrifier open、write 或 close 函數呼叫此函數。此函數通知 Proxy 伺服器已處理回應，且 Transmogrifier 步驟完成。

void  HTTPD_LINKAGE  HTTPD_close (
         unsigned char *handle,       /* i; handle */
         long *return_code            /* o; 回覆碼 */
         )

HTTPD_exec()

會執行 Script 以滿足此要求。在 PreExit、Service、PostAuthorization 及 Error 步驟中有效。

void  HTTPD_LINKAGE  HTTPD_exec (
         unsigned char *handle,         /* i; handle */
         unsigned char *name,           /* i; 要執行的 Script 名稱 */
         unsigned long *name_length,    /* i; 名稱的長度 */
         long *return_code              /* o; 回覆碼 */
         )

HTTPD_extract()

會擷取與此要求相關聯的變數值。name 參數的有效變數與 CGI 中使用的那些變數相同。如需相關資訊，請參閱變數。請注意，此函數在所有步驟中都有效；不過，並非所有變數在所有步驟中都有效。

void  HTTPD_LINKAGE  HTTPD_extract (
      unsigned char *handle,       /* i; handle */
      unsigned char *name,         /* i; 要擷取的變數名稱 */
      unsigned long *name_length,  /* i; 名稱的長度 */
      unsigned char *value,        /* o; 在其中放置
                                         值的緩衝區 */
      unsigned long *value_length, /* i/o; 緩衝區大小 */
      long *return_code            /* o; 回覆碼 */
      )

若此函數傳回 HTTPD_BUFFER_TOO_SMALL 回覆碼，則表示您所要求的緩衝區對擷取的值而言不夠大。在此情況下，函數就不會使用緩衝區，但會以您需要的緩衝區大小更新 value_length 參數，以順利擷取此值。使用至少與傳回的 value_length 一樣大的緩衝區來重試擷取。

註：

如果要擷取的變數是用於 HTTP 標頭，HTTPD_extract() 函數只會擷取第一個符合的出現項目，即使該要求含有多個具備相同名稱的標頭也是如此。您可以使用 httpd_getvar() 函數代替 HTTPD_extract()，同時享有其他好處。如需相關資訊，請參閱httpd_getvar() 函數的章節。

HTTPD_file()

會傳送檔案以滿足此要求。只在 PreExit、Service、Error、PostAuthorization 及 Transmogrifier 步驟中有效。

void  HTTPD_LINKAGE  HTTPD_file (
         unsigned char *handle,          /* i; handle */
         unsigned char *name,            /* i; 要傳送的檔案名稱 */
         unsigned long *name_length,     /* i; 名稱的長度 */
         long *return_code               /* o; 回覆碼 */
         )

httpd_getvar()

與 HTTPD_extract() 相同，不過更容易使用，因為使用者不必指定引數的長度。

const  unsigned char *          /* o; 變數的值 */
HTTPD_LINKAGE
httpd_getvar(
   unsigned char *handle,       /* i; handle */
   unsigned char *name,         /* i; 變數名稱 */
   unsigned long *n             /* i; 陣列的索引號碼
                                      此陣列包含標頭 */
   )

包含標頭的陣列索引是以 0 為開頭。如果要取得陣列中的第一個項目，請對 n 使用 0 值；如果要取得第五個項目，請對 n 使用 4 值。

註：

請勿捨棄或變更回覆值的內容。傳回的字串以空值終止。

HTTPD_log_access()

將字串寫入伺服器的存取日誌中。

void  HTTPD_LINKAGE  HTTPD_log_access (
         unsigned char *handle,           /* i; handle */
         unsigned char *value,            /* i; 寫入的資料 */
         unsigned long *value_length,     /* i; 資料的長度 */
         long *return_code                /* o; 回覆碼 */
         )

請注意，在伺服器存取日誌中寫入百分比符號 (%) 時，不需要跳出符號。

HTTPD_log_error()

將字串寫入伺服器的錯誤日誌中。

void  HTTPD_LINKAGE  HTTPD_log_error (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; 寫入的資料 */
         unsigned long *value_length,    /* i; 資料的長度 */
         long *return_code               /* o; 回覆碼 */
         )

請注意，在伺服器錯誤日誌中寫入百分比符號 (%) 時，不需要跳出符號。

HTTPD_log_event()

將字串寫入伺服器的事件日誌中。

void  HTTPD_LINKAGE  HTTPD_log_event (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; 寫入的資料 */
         unsigned long *value_length,    /* i; 資料的長度 */
         long *return_code               /* o; 回覆碼 */
         )

請注意，在伺服器事件日誌中寫入百分比符號 (%) 時，不需要跳出符號。

HTTPD_log_trace()

將字串寫入伺服器的追蹤日誌中。

void  HTTPD_LINKAGE  HTTPD_log_trace (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; 寫入的資料 */
         unsigned long *value_length,    /* i; 資料的長度 */
         long *return_code               /* o; 回覆碼 */
         )

請注意，在伺服器追蹤日誌中寫入百分比符號 (%) 時，不需要跳出符號。

HTTPD_open()

（只在 Transmogrifier 步驟中有效。）將控制權轉交給串流堆疊中的下一個常式。在您設定任何所要的標頭，且準備開始寫入常式之後，請從 Transmogrifier open、write 或 close 函數呼叫此函數。

void  HTTPD_LINKAGE  HTTPD_open (
         unsigned char *handle,      /* i; handle */
         long *return_code           /* o; 回覆碼 */
         )

HTTPD_proxy()

提出 Proxy 要求。在 PreExit、Service 及 PostAuthorization 步驟中有效。

註：

這是一個完成函數；表示要求在此函數之後完成。

void  HTTPD_LINKAGE  HTTPD_proxy (
         unsigned char *handle,        /* i; handle */
         unsigned char *url_name,      /* i;
                                             Proxy 要求的 URL */
         unsigned long *name_length,   /* i; URL 的長度 */
         void *request_body,           /* i; 要求的主體 */
         unsigned long *body_length,   /* i; 主體的長度 */
         long *return_code             /* o; 回覆碼 */
         )

HTTPD_read()

會讀取用戶端要求的主體。請對標頭使用 HTTPD_extract()。只在 PreExit、Authorization、PostAuthorization 及 Service 步驟中有效，且唯有執行 PUT 或 POST 要求之後才有用。在 HTTPD_EOF 傳回之前，會在迴圈中呼叫此函數。若此要求沒有任何主體，則此函數會失敗。

void  HTTPD_LINKAGE  HTTPD_read (
         unsigned char *handle,          /* i; handle */
         unsigned char *value,           /* i; 資料的緩衝區 */
         unsigned long *value_length,    /* i/o; 緩衝區大小
                                                 （資料長度） */
         long *return_code               /* o; 回覆碼 */
         )

HTTPD_restart()

在處理所有作用中要求之後，重新啟動伺服器。除了「伺服器起始設定」、「伺服器終止」及 Transmogrifier 以外，在其他所有步驟中都有效。

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code    /* o; 回覆碼 */
         )

HTTPD_set()

會設定與此要求相關聯的變數值。對 name 參數有效的變數與 CGI 中使用的那些變數相同。如需相關資訊，請參閱變數。

請注意，您也可以使用此函數建立變數。您建立的變數需要遵循 HTTP_ 和 PROXY_ 字首的使用慣例，如變數中的說明。如果您是以 HTTP_ 為開頭來建立變數，其在用戶端回應中就會以標頭的形式傳送，而不含 HTTP_ 字首。例如，要設定位置標頭，請使用含有變數名稱 HTTP_LOCATION 的 HTTPD_set()。如果您是以 PROXY_ 字首來建立變數，其在內容伺服器要求中就會以標頭的形式傳送。如果您是以 CGI_ 字首來建立變數，其會傳遞至 CGI 程式。

此函數在所有步驟中都有效；不過，並非所有變數在所有步驟中都有效。

void  HTTPD_LINKAGE  HTTPD_set (
         unsigned char *handle,        /* i; handle */
         unsigned char *name,          /* i; 要設定的值名稱 */
         unsigned long *name_length,   /* i; 名稱的長度 */
         unsigned char *value,         /* i; 含有值的緩衝區 */
         unsigned long *value_length,  /* i; 值的長度 */
         long *return_code             /* o; 回覆碼 */
         )

註：

您可以使用 httpd_setvar() 函數設定變數值，而不必指定緩衝區和長度。如需相關資訊，請參閱 httpd_setvar() 函數的章節。

httpd_setvar()

與 HTTPD_set() 相同，不過更容易使用，因為使用者不必指定引數的長度。

long             /* o; 回覆碼 */
HTTPD_LINKAGE   httpd_setvar (
       unsigned char *handle,       /* i; handle */
       unsigned char *name,         /* i; 變數名稱 */
       unsigned char *value,        /* i; 新值 */
       unsigned long *addHdr        /* i; 新增標頭或取代它 */
       )

addHdr

參數有四個可能值：

HTTPD_SETVAR_REPLACE — 以新值取代所有出現的標頭變數。
HTTPD_SETVAR_REPLACE_ADD — 如果存在標頭變數，請以新值取代第一次出現的變數；如果不存在該變數，請將新值附加在標頭後面。
HTTPD_SETVAR_ADD — 將此值附加在標頭後面。
HTTPD_SETVAR_REMOVE_ALL — 刪除所有出現的這個標頭變數。

這些值定義在 HTAPI.h 中。

httpd_variant_insert()

會將變式插入快取中。

void  HTTPD_LINKAGE  httpd_variant_insert (
         unsigned char *handle,    /* i; handle */
         unsigned char *URI,       /* i; 此物件的 URI */
         unsigned char *dimension, /* i; 變式的維度 */
         unsigned char *variant,   /* i; 變式的值 */
         unsigned char *filename,  /* i; 包含物件的檔案 */
         long *return_code         /* o; 回覆碼 */
         )

附註：

維度引數參照的標頭，讓此物件與 URI 有所不同。例如，在上面的範例中，可能的維度值是 User-Agent。
變式引數參照標頭的值，那是在維度引數中給定的標頭。這與 URI 不同。例如，在上面的範例中，變式引數的可能值如下：
```
Mozilla 4.0（相容的；BatBrowser 94.1.2；Bat OS）
```
檔名引數必須指向以空值結尾的檔名副本，使用者可在其中儲存所修改的內容。使用者負責移除該檔案；從此函數傳回之後，此動作是安全的。此檔案只包含主體，不含標頭。
快取變式時，伺服器會更新 content-length 標頭，並新增警告：214 標頭。會移除強實體標籤。

httpd_variant_lookup()

會判斷給定的變式是否存在於快取中。

void  HTTPD_LINKAGE  httpd_variant_lookup (
    unsigned char *handle,             /* i; handle */
    unsigned char *URI,                /* 此物件的 URI */
    unsigned char *dimension,          /* i; 變式的維度 */
    unsigned char *variant,            /* i; 變式的值 */
             long *return_code);       /* o; 回覆碼 */

HTTPD_write()

寫入回應的主體。在 PreExit、Service、Error 及 Transmogrifier 步驟中有效。

第一次呼叫此函數之前，如果您尚未設定內容類型，伺服器會假設您傳送的是 CGI 資料串流。

void  HTTPD_LINKAGE  HTTPD_write (
    unsigned char *handle,             /* i; handle */
    unsigned char *value,              /* i; 傳送的資料 */
    unsigned char *value_length,       /* i; 資料的長度 */
             long *return_code);       /* o; 回覆碼 */

註：

如果要設定回應標頭，請參閱 HTTPD_set() 函數的章節。

註：

在 HTTPD_* 函數傳回之後，您可以放心地釋放您用它傳遞的任何記憶體。

來自預先定義的函數和巨集的回覆碼

伺服器會視要求成功與否，將回覆碼參數設為下列其中一值：

表 3. 回覆碼
值	狀態碼	說明
-1	HTTPD_UNSUPPORTED	不支援此函數。
0	HTTPD_SUCCESS	此函數成功，且輸出欄位有效。
1	HTTPD_FAILURE	此函數失敗。
2	HTTPD_INTERNAL_ERROR	發現內部錯誤，此要求的處理無法繼續。
3	HTTPD_PARAMETER_ERROR	已傳遞一個或多個無效參數。
4	HTTPD_STATE_CHECK	此函數在此處理程序步驟中無效。
5	HTTPD_READ_ONLY	（只由 HTTPD_set 和 httpd_setvar 傳回。）此變數為唯讀，且無法由外掛程式設定。
6	HTTPD_BUFFER_TOO_SMALL	（由 HTTPD_set、httpd_setvar 和 HTTPD_read 傳回。）提供的緩衝區太小。
7	HTTPD_AUTHENTICATE_FAILED	（只由 HTTPD_authenticate 傳回。）鑑別失敗。如需相關資訊，請檢查 HTTP_RESPONSE 和 HTTP_REASON 變數。
8	HTTPD_EOF	（只由 HTTPD_read 傳回。）指出要求內文結束。
9	HTTPD_ABORT_REQUEST	此要求中斷，因為用戶端提供的實體標籤不符合該要求指定的條件。
10	HTTPD_REQUEST_SERVICED	（由 HTTPD_proxy 傳回。）呼叫的函數已完成此要求的回應。
11	HTTPD_RESPONSE_ALREADY_COMPLETED	此函數失敗，因為該要求的回應已完成。
12	HTTPD_WRITE_ONLY	此變數為唯寫，且無法由外掛程式讀取。

API 步驟的 Caching Proxy 配置指引

在要求處理程序中，每一個步驟都有一個配置指引，您可以利用它來指示在該步驟期間要呼叫及執行的外掛程式函數。您可以手動編輯和更新，或利用 Caching Proxy「配置」和「管理」表單中的「API 要求處理程序」表單，將這些指引新增至伺服器的配置檔 (ibmproxy.conf)。

API 使用注意事項

除了 Service 和 NameTrans 指引之外，每一個步驟的 API 指引並不需要以任何特定順序出現在配置檔中。請注意，在一個 API 指引中，多個項目的順序很重要，如此清單稍後所述。
不一定要包含每一個 API 步驟的項目。如果您沒有特定步驟的外掛程式，則不會執行對應的指引，將使用該步驟的標準處理程序。
Service 和 NameTrans 指引的運作方式類似其他對映指引（例如：Pass 指引），且會視其相對於配置檔內其他對映指引的出現和放置而定。例如，/cgi-bin/foo.so 的規則必須出現在 /cgi-bin/* 的規則之前。
這表示伺服器會依 Service、NameTrans、Exec、Fail、Map、Pass、Proxy、ProxyWAS 和 Redirect 指引在配置檔內的順序來處理它們。當伺服器成功將 URL 對映到檔案時，它不會讀取或處理任何其他這些指引。（Map 指引例外。如需 Proxy 伺服器對映規則的完整相關資訊，請參閱 WebSphere Application Server Caching Proxy 管理手冊。）
一個步驟可以有多個配置指引。例如，您可以包括兩個 NameTrans 指引，每一個指向不同的外掛程式函數。當伺服器執行 Name Translation 步驟時，它會依名稱轉換函數出現在配置檔內的順序來處理名稱轉換函數。

註：

如果隨 Caching Proxy 提供的外掛程式函數，會使用與您撰寫的外掛程式相同的 API 指引，請將您外掛程式的指引置於系統外掛程式指引之後。
部分外掛程式函數不需要對每一個要求執行：
- 有數個指引包括 URL 遮罩。使用這些指引指定 URL 遮罩，會導致只對其 URL 符合該型樣的要求呼叫外掛程式應用程式。請參閱 API 指引和語法，以取得哪些步驟可以使用 URL 遮罩的相關資訊，並參閱 API 指引變數，以取得如何使用此功能的相關資訊。
- 以 Authentication 指引指定鑑別方法，指出您想只對哪些特定鑑別類型呼叫該外掛程式。目前，HTTP 通訊協定只支援基本鑑別 (BA)。如需相關資訊，請參閱 API 指引變數。
如果伺服器無法載入特定的外掛程式函數，或您擁有的 ServerInit 指引未傳回 OK 回覆碼，則不會呼叫這個已編譯的 Caching Proxy 外掛程式的其他外掛程式函數。會忽略到目前為止對該外掛程式所執行的任何特定處理。您併入這些指引中的其他 Caching Proxy 外掛程式及其函數都不受影響。

API 指引和語法

這些配置檔指引必須以同一行出現在 ibmproxy.conf 檔中，且除了此處明確指定的部分以外，不可含有空格。雖然在某些語法範例中，出現換行是基於可讀性，但是在實際指引中的那些換行點上，不得含有空格。

表 4. Caching Proxy 外掛程式 API 指引
ServerInit		`/path/file:function_name init_string`
PreExit		`/path/file:function_name`
鑑別	`type`	`/path/file:function_name`
NameTrans	`/URL`	`/path/file:function_name`
授權	`/URL`	`/path/file:function_name`
ObjectType	`/URL`	`/path/file:function_name`
PostAuth		`/path/file:function_name`
服務	`/URL`	`/path/file:function_name`
午夜		`/path/file:function_name`
Transmogrifier		`/path/file:open_function_name: write_function_name: close_function_name:error_function`

日誌	`/URL`	`/path/file:function_name`
錯誤	`/URL`	`/path/file:function_name`
PostExit		`/path/file:function_name`
ServerTerm		`/path/file:function_name`
ProxyAdvisor		`/path/file:function_name`
GCAdvisor		`/path/file:function_name`

API 指引變數

這些指引中的變數有下列意義：

類型

只與 Authentication 指引一起使用，以指定是否呼叫外掛程式函數。有效值如下：

基本 — 只對基本鑑別 (BA) 要求呼叫外掛程式函數。
* — 對所有要求呼叫外掛程式函數。目前，HTTP 通訊協定只支援基本鑑別 (BA)。對於非基本鑑別要求，您可以傳回錯誤碼，指出此鑑別類型不受支援。

URL

指定要呼叫外掛程式函數的要求。如果要求含有符合這個範本的 URL，將導致使用外掛程式函數。這些指引中的 URL 規格是虛擬的（它們不包括通訊協定），但它們前面有一條斜線 (/)。因此 /www.ics.raleigh.ibm.com 正確，但 http://www.ics.raleigh.ibm.com 不正確。您可以指定此值作為特定的 URL 或作為範本。

特定的 URL — 只對該確切的 URL 呼叫外掛程式函數。
URL 範本 — 會對符合範本的所有 URL 呼叫外掛程式函數。範本可包含萬用字元 *，且可以用 /URL* 或 /* 或 * 形式指定

註：

如果您希望發生路徑轉換，則 Service 指引需要 URL 範本。

path/file

已編譯程式的完整檔名。

function_name

您在程式內提供給外掛程式函數的名稱。

如果您想要具備路徑資訊的存取權，則 Service 指引需要在函數名稱之後加一個星號 (*)。

init_string

這個 ServerInit 指引的選用部分，可包含您要傳遞至外掛程式函數的任何文字。請使用 httpd_getvar() 從 INIT_STRING 變數擷取文字。

如需這些指引相關資訊（包括語法），請參閱 WebSphere Application Server Caching Proxy 管理手冊。