Return to README.NEW-OUTPUT-API CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php

Annotation of embedaddon/php/README.NEW-OUTPUT-API, revision 1.1.1.1

1.1       misho       1: $Id: README.NEW-OUTPUT-API 219039 2006-08-30 07:39:09Z mike $
                      2: 
                      3: 
                      4: API adjustment to the old output control code:
                      5: 
                      6:        Everything now resides beneath the php_output namespace, 
                      7:        and there's an API call for every output handler op.
                      8: 
                      9:        Checking output control layers status:
                     10:                // Using OG()
                     11:                php_output_get_status(TSRMLS_C);
                     12: 
                     13:        Starting the default output handler:
                     14:                // php_start_ob_buffer(NULL, 0, 1 TSRMLS_CC);
                     15:                php_output_start_default(TSRMLS_C);
                     16: 
                     17:        Starting an user handler by zval:
                     18:                // php_start_ob_buffer(zhandler, chunk_size, erase TSRMLS_CC);
                     19:                php_output_start_user(zhandler, chunk_size, flags TSRMLS_CC);
                     20: 
                     21:        Starting an internal handler whithout context:
                     22:                // php_ob_set_internal_handler(my_php_output_handler_func_t, buffer_size, "output handler name", erase TSRMLS_CC);
                     23:                php_output_start_internal(handler_name, handler_name_len, my_php_output_handler_func_t, chunk_size, flags TSRMLS_CC);
                     24: 
                     25:        Starting an internal handler with context:
                     26:                // not possible with old API
                     27:                php_output_handler *h;
                     28:                h = php_output_handler_create_internal(handler_name, handler_name_len, my_php_output_handler_context_func_t, chunk_size, flags TSRMLS_CC);
                     29:                php_output_handler_set_context(h, my_context, my_context_dtor);
                     30:                php_output_handler_start(h TSRMLS_CC);
                     31: 
                     32:        Testing whether a certain output handler has already been started:
                     33:                // php_ob_handler_used("output handler name" TSRMLS_CC);
                     34:                php_output_handler_started(handler_name, handler_name_len TSRMLS_CC);
                     35: 
                     36:        Flushing one output buffer:
                     37:                // php_ob_end_buffer(1, 1 TSRMLS_CC);
                     38:                php_output_flush(TSRMLS_C);
                     39: 
                     40:        Flushing all output buffers:
                     41:                // not possible with old API
                     42:                php_output_flush_all(TSRMLS_C);
                     43: 
                     44:        Cleaning one output buffer:
                     45:                // php_ob_end_buffer(0, 1 TSRMLS_CC);
                     46:                php_output_clean(TSRMLS_C);
                     47: 
                     48:        Cleaning all output buffers:
                     49:                // not possible with old API
                     50:                php_output_clean_all(TSRMLS_C);
                     51: 
                     52:        Discarding one output buffer:
                     53:                // php_ob_end_buffer(0, 0 TSRMLS_CC);
                     54:                php_output_discard(TSRMLS_C);
                     55: 
                     56:        Discarding all output buffers:
                     57:                // php_ob_end_buffers(0 TSRMLS_CC);
                     58:                php_output_discard_all(TSRMLS_C);
                     59: 
                     60:        Stopping (and dropping) one output buffer:
                     61:                // php_ob_end_buffer(1, 0 TSRMLS_CC)
                     62:                php_output_end(TSRMLS_C);
                     63: 
                     64:        Stopping (and dropping) all output buffers:
                     65:                // php_ob_end_buffers(1, 0 TSRMLS_CC);
                     66:                php_output_end_all(TSRMLS_C);
                     67: 
                     68:        Retrieving output buffers contents:
                     69:                // php_ob_get_buffer(zstring TSRMLS_CC);
                     70:                php_output_get_contents(zstring TSRMLS_CC);
                     71: 
                     72:        Retrieving output buffers length:
                     73:                // php_ob_get_length(zlength TSRMLS_CC);
                     74:                php_output_get_length(zlength TSRMLS_CC);
                     75: 
                     76:        Retrieving output buffering level:
                     77:                // OG(nesting_level);
                     78:                php_output_get_level(TSRMLS_C);
                     79: 
                     80:        Issue a warning because of an output handler conflict:
                     81:                // php_ob_init_conflict("to be started handler name", "to be tested if already started handler name" TSRMLS_CC);
                     82:                php_output_handler_conflict(new_handler_name, new_handler_name_len, set_handler_name, set_handler_name_len TSRMLS_CC);
                     83: 
                     84:        Registering a conflict checking function, which will be checked prior starting the handler:
                     85:                // not possible with old API, unless hardcoding into output.c
                     86:                php_output_handler_conflict_register(handler_name, handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC);
                     87: 
                     88:        Registering a reverse conflict checking function, which will be checked prior starting the specified foreign handler:
                     89:                // not possible with old API
                     90:                php_output_handler_reverse_conflict_register(foreign_handler_name, foreign_handler_name_len, my_php_output_handler_conflict_check_t TSRMLS_CC);
                     91: 
                     92:        Facilitating a context from within an output handler callable with ob_start():
                     93:                // not possible with old API
                     94:                php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ, (void *) &custom_ctx_ptr_ptr TSRMLS_CC);
                     95: 
                     96:        Disabling of the output handler by itself:
                     97:                //not possible with old API
                     98:                php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_DISABLE, NULL TSRMLS_CC);
                     99: 
                    100:        Marking an output handler immutable by itself because of irreversibility of its operation:
                    101:                // not possible with old API
                    102:                php_output_handler_hook(PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE, NULL TSRMLS_CC);
                    103: 
                    104:        Restarting the output handler because of a CLEAN operation:
                    105:                // not possible with old API
                    106:                if (flags & PHP_OUTPUT_HANDLER_CLEAN) { ... }
                    107: 
                    108:        Recognizing by the output handler itself if it gets discarded:
                    109:                // not possible with old API
                    110:                if ((flags & PHP_OUTPUT_HANDLER_CLEAN) && (flags & PHP_OUTPUT_HANDLER_FINAL)) { ... }
                    111: 
                    112: 
                    113: Output handler hooks
                    114: 
                    115:        The output handler can change its abilities at runtime. Eg. the gz handler can
                    116:        remove the CLEANABLE and REMOVABLE bits when the first output has passed through it;
                    117:        or handlers implemented in C to be used with ob_start() can contain a non-global
                    118:        context:
                    119:                PHP_OUTPUT_HANDLER_HOOK_GET_OPAQ
                    120:                        pass a void*** pointer as second arg to receive the address of a pointer
                    121:                        pointer to the opaque field of the output handler context
                    122:                PHP_OUTPUT_HANDLER_HOOK_GET_FLAGS
                    123:                        pass a int* pointer as second arg to receive the flags set for the output handler
                    124:                PHP_OUTPUT_HANDLER_HOOK_GET_LEVEL
                    125:                        pass a int* pointer as second arg to receive the level of this output handler
                    126:                        (starts with 0)
                    127:                PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
                    128:                        the second arg is ignored; marks the output handler to be neither cleanable
                    129:                        nor removable
                    130:                PHP_OUTPUT_HANDLER_HOOK_DISABLE
                    131:                        the second arg is ignored; marks the output handler as disabled
                    132: 
                    133: 
                    134: Open questions
                    135: 
                    136:        Should the userland API be adjusted and unified?
                    137:        
                    138:        Many bits of the manual (and very first implementation) do not comply
                    139:        with the behaviour of the current (to be obsoleted) code, thus should
                    140:        the manual or the behaviour be adjusted?
                    141: 
                    142: END