1. 上下文 · PHP擴展開發及內核應用

# 上下文每個流的上下文包含兩種內部消息類型. 首先最常用的是上下文選項. 這些值被安排在上下文中一個二維數組中, 通常用于改變流包裝器的初始化行為. 還有一種則是上下文參數, 它對于包裝器是未知的, 當前提供了一種方式用于在流包裝層內部的事件通知. ```c php_stream_context *php_stream_context_alloc(void); ``` 通過這個API調用可以創建一個上下文, 它將分配一些存儲空間并初始化用于保存上下文選項和參數的HashTable. 還會自動的注冊為一個請求終止后將被清理的資源. ## 設置選項設置上下文選項的內部API和用戶空間的API是等同的: ```c int php_stream_context_set_option(php_stream_context *context, const char *wrappername, const char *optionname, zval *optionvalue); ``` 下面是用戶空間的原型: ```c bool stream_context_set_option(resource $context, string $wrapper, string $optionname, mixed $value); ``` 它們的不同僅僅是用戶空間和內部需要的數據類型不同.下面的例子就是使用這兩個API調用, 通過內建包裝器發起一個HTTP請求, 并通過一個上下文選項覆寫了user_agent設置. ```c php_stream *php_varstream_get_homepage(const char *alt_user_agent TSRMLS_DC) { php_stream_context *context; zval tmpval; context = php_stream_context_alloc(TSRMLS_C); ZVAL_STRING(&tmpval, alt_user_agent, 0); php_stream_context_set_option(context, "http", "user_agent", &tmpval); return php_stream_open_wrapper_ex("http://www.php.net", "rb", REPORT_ERRORS | ENFORCE_SAFE_MODE, NULL, context); } ``` >譯者使用的php-5.4.10中php_stream_context_alloc()增加了線程安全控制, 因此相應的對例子進行了修改, 請讀者測試時注意. >這里要注意的是tmpval并沒有分配任何持久性的存儲空間, 它的字符串值是通過復制設置的. php_stream_context_set_option()會自動的對傳入的zval內容進行一次拷貝. # 取回選項用于取回上下文選項的API調用正好是對應的設置API的鏡像: ```c int php_stream_context_get_option(php_stream_context *context, const char *wrappername, const char *optionname, zval ***optionvalue); ``` 回顧前面, 上下文選項存儲在一個嵌套的HashTable中, 當從一個HashTable中取回值時, 一般的方法是傳遞一個指向zval **的指針給zend_hash_find(). 當然, 由于php_stream_context_get_option()是zend_hash_find()的一個特殊代理, 它們的語義是相同的. 下面是內建的http包裝器使用php_stream_context_get_option()設置user_agent的簡化版示例: ```c zval **ua_zval; char *user_agent = "PHP/5.1.0"; if (context && php_stream_context_get_option(context, "http", "user_agent", &ua_zval) == SUCCESS && Z_TYPE_PP(ua_zval) == IS_STRING) { user_agent = Z_STRVAL_PP(ua_zval); } ``` 這種情況下, 非字符串值將會被丟棄, 因為對用戶代理字符串而言, 數值是沒有意義的. 其他的上下文選項, 比如max_redirects, 則需要數字值, 由于在字符串的zval中存儲數字值并不通用, 所以需要執行一個類型轉換以使設置合法. 不幸的是這些變量是上下文擁有的, 因此它們不能直接轉換; 而需要首先進行隔離再進行轉換, 最終如果需要還要進行銷毀: ```c long max_redirects = 20; zval **tmpzval; if (context && php_stream_context_get_option(context, "http", "max_redirects", &tmpzval) == SUCCESS) { if (Z_TYPE_PP(tmpzval) == IS_LONG) { max_redirects = Z_LVAL_PP(tmpzval); } else { zval copyval = **tmpzval; zval_copy_ctor(&copyval); convert_to_long(&copyval); max_redirects = Z_LVAL(copyval); zval_dtor(&copyval); } } ``` >實際上, 在這個例子中, zval_dtor()并不是必須的. IS_LONG的變量并不需要zval容器之外的存儲空間, 因此zval_dtor()實際上不會有真正的操作. 在這個例子中包含它是為了完整性考慮, 對于字符串, 數組, 對象, 資源以及未來可能的其他類型, 就需要這個調用了. ## 參數雖然用戶空間API中看起來參數和上下文選項是類似的, 但實際上在語言內部的php_stream_context結構體中它們被定義為不同的成員. 目前只支持一個上下文參數: 通知器. php_stream_context結構體中的這個元素可以指向下面的php_stream_notifier結構體: ```c typedef struct { php_stream_notification_func func; void (*dtor)(php_stream_notifier *notifier); void *ptr; int mask; size_t progress, progress_max; } php_stream_notifier; ``` 當將一個php_stream_notifier結構體賦值給context->notifier時, 它將提供一個回調函數func, 在特定的流上發生下表中的PHP_STREAM_NOTIFY_*代碼表示的事件時被觸發. 每個事件將會對應下面第二張表中的PHP_STREAM_NOTIFY_SEVERITY_*的級別: <table> <tr> <tr><td>事件代碼</td><td>含義</td></tr> <tr><td>RESOLVE</td><td>主機地址解析完成. 多數基于套接字的包裝器將在連接之前執行這個查詢.</td></tr> <tr><td>CONNECT</td><td>套接字流連接到遠程資源完成.</td></tr> <tr><td>AUTH_REQUIRED</td><td>請求的資源不可用, 原因是訪問控制以及缺失授權</td></tr> <tr><td>MIME_TYPE_IS</td><td>遠程資源的mime-type不可用</td></tr> <tr><td>FILE_SIZE_IS</td><td>遠程資源當前可用大小</td></tr> <tr><td>REDIRECTED</td><td>原來的URL請求導致重定向到其他位置</td></tr> <tr><td>PROGRESS</td><td>由于額外數據的傳輸導致php_stream_notifier結構體的progress以及(可能的)progress_max元素被更新(進度信息, 請參考php手冊curl_setopt的CURLOPT_PROGRESSFUNCTION和CURLOPT_NOPROGRESS選項)</td></tr> <tr><td>COMPLETED</td><td>流上沒有更多的可用數據</td></tr> <tr><td>FAILURE</td><td>請求的URL資源不成功或未完成</td></tr> <tr><td>AUTH_RESULT</td><td>遠程系統已經處理了授權認證</td></tr> </table> <table> <tr><td>安全碼</td><td> </td></tr> <tr><td>INFO</td><td>信息更新. 等價于一個E_NOTICE錯誤</td></tr> <tr><td>WARN</td><td>小的錯誤條件. 等價于一個E_WARNING錯誤</td></tr> <tr><td>ERR</td><td>中斷錯誤條件. 等價于一個E_ERROR錯誤.</td></tr> </table> 通知器實現提供了一個便利指針*ptr用于存放額外數據. 這個指針指向的空間必須在上下文析構時被釋放, 因此必須指定一個dtor函數, 在上下文的最后一個引用離開它的作用域時調用這個dtor進行釋放. mask元素允許事件觸發限定特定的安全級別. 如果發生的事件沒有包含在mask中, 則通知器函數不會被觸發. 最后兩個元素progress和progress_max可以由流實現設置, 然而, 通知器函數應該避免使用這兩個值, 除非它接收到PHP_STREAM_NOTIFY_PROGRESS或PHP_STREAM_NOTIFY_FILE_SIZE_IS事件通知. 下面是一個php_stream_notification_func()回調原型的示例: ```c void php_sample6_notifier(php_stream_context *context, int notifycode, int severity, char *xmsg, int xcode, size_t bytes_sofar, size_t bytes_max, void *ptr TSRMLS_DC) { if (notifycode != PHP_STREAM_NOTIFY_FAILURE) { /* 忽略所有通知 */ return; } if (severity == PHP_STREAM_NOTIFY_SEVERITY_ERR) { /* 分發到錯誤處理函數 */ php_sample6_theskyisfalling(context, xcode, xmsg); return; } else if (severity == PHP_STREAM_NOTIFY_SEVERITY_WARN) { /* 日志記錄潛在問題 */ php_sample6_logstrangeevent(context, xcode, xmsg); return; } } ``` ## 默認上下文在php5.0中, 當用戶空間的流創建函數被調用時, 如果沒有傳遞上下文參數, 請求一般會使用默認的上下文. 這個上下文變量存儲在文件全局結構中: FG(default_context), 并且它可以和其他所有的php_stream_context變量一樣訪問. 當在用戶空間腳本執行流的創建時, 更好的方式是允許用戶指定一個上下文或者至少指定一個默認的上下文. 將用戶空間的zval *解碼得到php_stream_context可以使用php_steram_context_from_zval()宏完成, 比如下面改編自第14章"訪問流"的例子: ```c PHP_FUNCTION(sample6_fopen) { php_stream *stream; char *path, *mode; int path_len, mode_len; int options = ENFORCE_SAFE_MODE | REPORT_ERRORS; zend_bool use_include_path = 0; zval *zcontext = NULL; php_stream_context *context; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "ss|br", &path, &path_len, &mode, &mode_len, &use_include_path, &zcontext) == FAILURE) { return; } context = php_stream_context_from_zval(zcontext, 0); if (use_include_path) { options |= PHP_FILE_USE_INCLUDE_PATH; } stream = php_stream_open_wrapper_ex(path, mode, options, NULL, context); if (!stream) { RETURN_FALSE; } php_stream_to_zval(stream, return_value); } ``` 如果zcontext包含一個用戶空間的上下文資源, 通過ZEND_FETCH_RESOURCE()調用獲取到它關聯的指針設置到context中. 否則, 如果zcontext為NULL并且php_stream_context_from_zval()的第二個參數設置為非0值, 這個宏則直接返回NULL. 這個例子以及幾乎所有的核心流創建的用戶空間函數中, 第二個參數都被設置為0, 此時將使用FG(default_context)的值. ## links * [目錄](<preface.md>) * 16 [有趣的流](<16.md>) * 16.2 [過濾器](<16.2.md>)