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     ! 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