release/src/router/php/README.NEW-OUTPUT-API

   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