diff options
| -rw-r--r-- | README.NEW-OUTPUT-API | 296 |
1 files changed, 6 insertions, 290 deletions
diff --git a/README.NEW-OUTPUT-API b/README.NEW-OUTPUT-API index 82e3f485b5..7d9cc1016f 100644 --- a/README.NEW-OUTPUT-API +++ b/README.NEW-OUTPUT-API @@ -20,18 +20,18 @@ API adjustment to the old output control code: Starting an internal handler whithout context: // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC); - php_output_start_internal(handler_name_zval, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC); + php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC); Starting an internal handler with context: // not possible with old API php_output_handler *h; - h = php_output_handler_create_internal(handler_name_zval, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC); + h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC); php_output_handler_set_context(h, my_context, my_context_dtor); php_output_handler_start(h TSRMLS_CC); Testing whether a certain output handler has already been started: // php_ob_handler_used("output handler name" TSRMLS_CC); - php_output_handler_started(handler_name_zval TSRMLS_CC); + php_output_handler_started(handler_name, handler_name_len TSRMLS_CC); Flushing one output buffer: // php_ob_end_buffer(1, 1 TSRMLS_CC); @@ -79,299 +79,15 @@ API adjustment to the old output control code: Issue a warning because of an output handler conflict: // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC); - php_output_handler_conflict(new_handler_name_zval, set_handler_name_zval TSRMLS_CC); + php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len TSRMLS_CC); Registering a conflict checking function, which will be checked prior starting the handler: // not possible with old API, unless hardcoding into output.c - php_output_handler_conflict_register(handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC); + php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC); Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler: // not possible with old API - php_output_handler_reverse_conflict_register(foreign_handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC); - - Facilitating a context from within an output handler callable with ob_start(): - // not possible with old API - php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC); - - Disabling of the output handler by itself: - //not possible with old API - php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC); - - Marking an output handler immutable by itself because of irreversibility of its operation: - // not possible with old API - php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC); - - Restarting the output handler because of a CLEAN operation: - // not possible with old API - if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... } - - Recognizing by the output handler itself if it gets discarded: - // not possible with old API - if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... } - - -Output handler hooks - - The output handler can change its abilities at runtime. Eg. the gz handler can - remove the CLEANABLE and REMOVABLE bits when the first output has passed through it; - or handlers implemented in C to be used with ob_start() can contain a non-global - context: - PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ - pass a void*** pointer as second arg to receive the address of a pointer - pointer to the opaque field of the output handler context - PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS - pass a int* pointer as second arg to receive the flags set for the output handler - PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL - pass a int* pointer as second arg to receive the level of this output handler - (starts with 0) - PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE - the second arg is ignored; marks the output handler to be neither cleanable - nor removable - PHP_OUTPUT_HANDLER_HOOK_DISABLE - the second arg is ignored; marks the output handler as disabled - - -Open questions - - Should the userland API be adjusted and unified? - - Many bits of the manual (and very first implementation) do not comply - with the behaviour of the current (to be obsoleted) code, thus should - the manual or the behaviour be adjusted? - -END -$Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $ - - -API adjustment to the old output control code: - - Everything now resides beneath the php_output namespace, - and there's an API call for every output handler op. - - Checking output control layers status: - // Using OG() - php_output_get_status(TSRMLS_C); - - Starting the default output handler: - // php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC); - php_output_start_default(TSRMLS_C); - - Starting an user handler by zval: - // php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC); - php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC); - - Starting an internal handler whithout context: - // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC); - php_output_start_internal(handler_name_zval, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC); - - Starting an internal handler with context: - // not possible with old API - php_output_handler *h; - h = php_output_handler_create_internal(handler_name_zval, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC); - php_output_handler_set_context(h, my_context, my_context_dtor); - php_output_handler_start(h TSRMLS_CC); - - Testing whether a certain output handler has already been started: - // php_ob_handler_used("output handler name" TSRMLS_CC); - php_output_handler_started(handler_name_zval TSRMLS_CC); - - Flushing one output buffer: - // php_ob_end_buffer(1, 1 TSRMLS_CC); - php_output_flush(TSRMLS_C); - - Flushing all output buffers: - // not possible with old API - php_output_flush_all(TSRMLS_C); - - Cleaning one output buffer: - // php_ob_end_buffer(0, 1 TSRMLS_CC); - php_output_clean(TSRMLS_C); - - Cleaning all output buffers: - // not possible with old API - php_output_clean_all(TSRMLS_C); - - Discarding one output buffer: - // php_ob_end_buffer(0, 0 TSRMLS_CC); - php_output_discard(TSRMLS_C); - - Discarding all output buffers: - // php_ob_end_buffers(0 TSRMLS_CC); - php_output_discard_all(TSRMLS_C); - - Stopping (and dropping) one output buffer: - // php_ob_end_buffer(1, 0 TSRMLS_CC) - php_output_end(TSRMLS_C); - - Stopping (and dropping) all output buffers: - // php_ob_end_buffers(1, 0 TSRMLS_CC); - php_output_end_all(TSRMLS_C); - - Retrieving output buffers contents: - // php_ob_get_buffer(zstring TSRMLS_CC); - php_output_get_contents(zstring TSRMLS_CC); - - Retrieving output buffers length: - // php_ob_get_length(zlength TSRMLS_CC); - php_output_get_length(zlength TSRMLS_CC); - - Retrieving output buffering level: - // OG(nesting_level); - php_output_get_level(TSRMLS_C); - - Issue a warning because of an output handler conflict: - // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC); - php_output_handler_conflict(new_handler_name_zval, set_handler_name_zval TSRMLS_CC); - - Registering a conflict checking function, which will be checked prior starting the handler: - // not possible with old API, unless hardcoding into output.c - php_output_handler_conflict_register(handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC); - - Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler: - // not possible with old API - php_output_handler_reverse_conflict_register(foreign_handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC); - - Facilitating a context from within an output handler callable with ob_start(): - // not possible with old API - php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC); - - Disabling of the output handler by itself: - //not possible with old API - php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC); - - Marking an output handler immutable by itself because of irreversibility of its operation: - // not possible with old API - php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC); - - Restarting the output handler because of a CLEAN operation: - // not possible with old API - if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... } - - Recognizing by the output handler itself if it gets discarded: - // not possible with old API - if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... } - - -Output handler hooks - - The output handler can change its abilities at runtime. Eg. the gz handler can - remove the CLEANABLE and REMOVABLE bits when the first output has passed through it; - or handlers implemented in C to be used with ob_start() can contain a non-global - context: - PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ - pass a void*** pointer as second arg to receive the address of a pointer - pointer to the opaque field of the output handler context - PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS - pass a int* pointer as second arg to receive the flags set for the output handler - PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL - pass a int* pointer as second arg to receive the level of this output handler - (starts with 0) - PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE - the second arg is ignored; marks the output handler to be neither cleanable - nor removable - PHP_OUTPUT_HANDLER_HOOK_DISABLE - the second arg is ignored; marks the output handler as disabled - - -Open questions - - Should the userland API be adjusted and unified? - - Many bits of the manual (and very first implementation) do not comply - with the behaviour of the current (to be obsoleted) code, thus should - the manual or the behaviour be adjusted? - -END -$Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $ - - -API adjustment to the old output control code: - - Everything now resides beneath the php_output namespace, - and there's an API call for every output handler op. - - Checking output control layers status: - // Using OG() - php_output_get_status(TSRMLS_C); - - Starting the default output handler: - // php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC); - php_output_start_default(TSRMLS_C); - - Starting an user handler by zval: - // php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC); - php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC); - - Starting an internal handler whithout context: - // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC); - php_output_start_internal(handler_name_zval, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC); - - Starting an internal handler with context: - // not possible with old API - php_output_handler *h; - h = php_output_handler_create_internal(handler_name_zval, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC); - php_output_handler_set_context(h, my_context, my_context_dtor); - php_output_handler_start(h TSRMLS_CC); - - Testing whether a certain output handler has already been started: - // php_ob_handler_used("output handler name" TSRMLS_CC); - php_output_handler_started(handler_name_zval TSRMLS_CC); - - Flushing one output buffer: - // php_ob_end_buffer(1, 1 TSRMLS_CC); - php_output_flush(TSRMLS_C); - - Flushing all output buffers: - // not possible with old API - php_output_flush_all(TSRMLS_C); - - Cleaning one output buffer: - // php_ob_end_buffer(0, 1 TSRMLS_CC); - php_output_clean(TSRMLS_C); - - Cleaning all output buffers: - // not possible with old API - php_output_clean_all(TSRMLS_C); - - Discarding one output buffer: - // php_ob_end_buffer(0, 0 TSRMLS_CC); - php_output_discard(TSRMLS_C); - - Discarding all output buffers: - // php_ob_end_buffers(0 TSRMLS_CC); - php_output_discard_all(TSRMLS_C); - - Stopping (and dropping) one output buffer: - // php_ob_end_buffer(1, 0 TSRMLS_CC) - php_output_end(TSRMLS_C); - - Stopping (and dropping) all output buffers: - // php_ob_end_buffers(1, 0 TSRMLS_CC); - php_output_end_all(TSRMLS_C); - - Retrieving output buffers contents: - // php_ob_get_buffer(zstring TSRMLS_CC); - php_output_get_contents(zstring TSRMLS_CC); - - Retrieving output buffers length: - // php_ob_get_length(zlength TSRMLS_CC); - php_output_get_length(zlength TSRMLS_CC); - - Retrieving output buffering level: - // OG(nesting_level); - php_output_get_level(TSRMLS_C); - - Issue a warning because of an output handler conflict: - // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC); - php_output_handler_conflict(new_handler_name_zval, set_handler_name_zval TSRMLS_CC); - - Registering a conflict checking function, which will be checked prior starting the handler: - // not possible with old API, unless hardcoding into output.c - php_output_handler_conflict_register(handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC); - - Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler: - // not possible with old API - php_output_handler_reverse_conflict_register(foreign_handler_name_zval, my_php_output_handler_conflict_check_t TSRMLS_CC); + php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC); Facilitating a context from within an output handler callable with ob_start(): // not possible with old API |