舊式緩衝協定 (Buffer Protocol)
******************************

在 3.0 版之後被棄用.

這些函式是 Python 2 中「舊式緩衝區協定」API 的一部分。在 Python 3 中，
該協議已經不存在，但這些函式仍有公開以供移植 2.x 程式碼。它們充當新式
緩衝區協定的相容性包裝器，但它們無法讓你控制匯出 (export) 緩衝區時所獲
取資源的生命週期。

因此，建議你呼叫 "PyObject_GetBuffer()" （或是以 "y*" 或 "w*" 格式碼
(format code) 呼叫 "PyArg_ParseTuple()" 系列函式）獲取物件的緩衝區視圖
(buffer view)，以及緩衝區視圖可被釋放時呼叫 "PyBuffer_Release()" 。

int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
    * 為 穩定 ABI 的一部分.*

   回傳一個指向可用作基於字元輸入之唯讀記憶體位置的指標。 *obj* 引數必
   須支援單一片段 (single-segment) 字元緩衝區介面。成功時回傳 "0"，並
   將 *buffer* 設定為記憶體位置、將 *buffer_len* 設定為緩衝區長度。回
   傳 "-1" 並在錯誤時設定 "TypeError"。

int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
    * 為 穩定 ABI 的一部分.*

   回傳一個指向包含任意資料之唯讀記憶體位置的指標。*obj* 引數必須支援
   單一片段可讀緩衝區介面。成功時回傳 "0"，並將 *buffer* 設定為記憶體
   位置、將 *buffer_len* 設定為緩衝區長度。回傳 "-1" 並在錯誤時設定
   "TypeError"。

int PyObject_CheckReadBuffer(PyObject *o)
    * 為 穩定 ABI 的一部分.*

   如果 *o* 支援單一片段可讀緩衝區介面，則回傳 "1"，否則回傳 "0"。這個
   函式一定會執行成功的。

   請注意，該函式嘗試獲取和釋放緩衝區，並且呼叫相應函式時發生的例外將
   被抑制。要獲取錯誤報告，請改用 "PyObject_GetBuffer()"。

int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
    * 為 穩定 ABI 的一部分.*

   回傳指向可寫記憶體位置的指標。 *obj* 引數必須支援單一片段字元緩衝區
   介面。成功時回傳 "0"，並將 *buffer* 設定為記憶體位置，且將
   *buffer_len* 設定為緩衝區長度。回傳 "-1" 並在錯誤時設定 "TypeError"
   。
