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
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>