xref: /PHP-8.3/main/streams/php_stream_context.h (revision d22d0e26)
1 /*
2    +----------------------------------------------------------------------+
3    | Copyright (c) The PHP Group                                          |
4    +----------------------------------------------------------------------+
5    | This source file is subject to version 3.01 of the PHP license,      |
6    | that is bundled with this package in the file LICENSE, and is        |
7    | available through the world-wide-web at the following url:           |
8    | https://www.php.net/license/3_01.txt                                 |
9    | If you did not receive a copy of the PHP license and are unable to   |
10    | obtain it through the world-wide-web, please send a note to          |
11    | license@php.net so we can mail you a copy immediately.               |
12    +----------------------------------------------------------------------+
13    | Author: Wez Furlong <wez@thebrainroom.com>                           |
14    +----------------------------------------------------------------------+
15  */
16 
17 /* Stream context and status notification related definitions */
18 
19 /* callback for status notifications */
20 typedef void (*php_stream_notification_func)(php_stream_context *context,
21 		int notifycode, int severity,
22 		char *xmsg, int xcode,
23 		size_t bytes_sofar, size_t bytes_max,
24 		void * ptr);
25 
26 #define PHP_STREAM_NOTIFIER_PROGRESS	1
27 
28 /* Attempt to fetch context from the zval passed,
29    If no context was passed, use the default context
30    The default context has not yet been created, do it now. */
31 #define php_stream_context_from_zval(zcontext, nocontext) ( \
32 		(zcontext) ? zend_fetch_resource_ex(zcontext, "Stream-Context", php_le_stream_context()) : \
33 		(nocontext) ? NULL : \
34 		FG(default_context) ? FG(default_context) : \
35 		(FG(default_context) = php_stream_context_alloc()) )
36 
37 #define php_stream_context_to_zval(context, zval) { ZVAL_RES(zval, (context)->res); GC_ADDREF((context)->res); }
38 
39 typedef struct _php_stream_notifier php_stream_notifier;
40 
41 struct _php_stream_notifier {
42 	php_stream_notification_func func;
43 	void (*dtor)(php_stream_notifier *notifier);
44 	zval ptr;
45 	int mask;
46 	size_t progress, progress_max; /* position for progress notification */
47 };
48 
49 struct _php_stream_context {
50 	php_stream_notifier *notifier;
51 	zval options;	/* hash keyed by wrapper family or specific wrapper */
52 	zend_resource *res;	/* used for auto-cleanup */
53 };
54 
55 BEGIN_EXTERN_C()
56 PHPAPI void php_stream_context_free(php_stream_context *context);
57 PHPAPI php_stream_context *php_stream_context_alloc(void);
58 PHPAPI zval *php_stream_context_get_option(php_stream_context *context,
59 		const char *wrappername, const char *optionname);
60 PHPAPI void php_stream_context_set_option(php_stream_context *context,
61 		const char *wrappername, const char *optionname, zval *optionvalue);
62 
63 PHPAPI php_stream_notifier *php_stream_notification_alloc(void);
64 PHPAPI void php_stream_notification_free(php_stream_notifier *notifier);
65 END_EXTERN_C()
66 
67 /* not all notification codes are implemented */
68 #define PHP_STREAM_NOTIFY_RESOLVE		1
69 #define PHP_STREAM_NOTIFY_CONNECT		2
70 #define PHP_STREAM_NOTIFY_AUTH_REQUIRED		3
71 #define PHP_STREAM_NOTIFY_MIME_TYPE_IS	4
72 #define PHP_STREAM_NOTIFY_FILE_SIZE_IS	5
73 #define PHP_STREAM_NOTIFY_REDIRECTED	6
74 #define PHP_STREAM_NOTIFY_PROGRESS		7
75 #define PHP_STREAM_NOTIFY_COMPLETED		8
76 #define PHP_STREAM_NOTIFY_FAILURE		9
77 #define PHP_STREAM_NOTIFY_AUTH_RESULT	10
78 
79 #define PHP_STREAM_NOTIFY_SEVERITY_INFO	0
80 #define PHP_STREAM_NOTIFY_SEVERITY_WARN	1
81 #define PHP_STREAM_NOTIFY_SEVERITY_ERR	2
82 
83 BEGIN_EXTERN_C()
84 PHPAPI void php_stream_notification_notify(php_stream_context *context, int notifycode, int severity,
85 		char *xmsg, int xcode, size_t bytes_sofar, size_t bytes_max, void * ptr);
86 PHPAPI php_stream_context *php_stream_context_set(php_stream *stream, php_stream_context *context);
87 END_EXTERN_C()
88 
89 #define php_stream_notify_info(context, code, xmsg, xcode)	do { if ((context) && (context)->notifier) { \
90 	php_stream_notification_notify((context), (code), PHP_STREAM_NOTIFY_SEVERITY_INFO, \
91 				(xmsg), (xcode), 0, 0, NULL); } } while (0)
92 
93 #define php_stream_notify_progress(context, bsofar, bmax) do { if ((context) && (context)->notifier) { \
94 	php_stream_notification_notify((context), PHP_STREAM_NOTIFY_PROGRESS, PHP_STREAM_NOTIFY_SEVERITY_INFO, \
95 			NULL, 0, (bsofar), (bmax), NULL); } } while(0)
96 
97 #define php_stream_notify_completed(context) do { if ((context) && (context)->notifier) { \
98 	php_stream_notification_notify((context), PHP_STREAM_NOTIFY_COMPLETED, PHP_STREAM_NOTIFY_SEVERITY_INFO, \
99 			NULL, 0, (context)->notifier->progress, (context)->notifier->progress_max, NULL); } } while(0)
100 
101 #define php_stream_notify_progress_init(context, sofar, bmax) do { if ((context) && (context)->notifier) { \
102 	(context)->notifier->progress = (sofar); \
103 	(context)->notifier->progress_max = (bmax); \
104 	(context)->notifier->mask |= PHP_STREAM_NOTIFIER_PROGRESS; \
105 	php_stream_notify_progress((context), (sofar), (bmax)); } } while (0)
106 
107 #define php_stream_notify_progress_increment(context, dsofar, dmax) do { if ((context) && (context)->notifier && ((context)->notifier->mask & PHP_STREAM_NOTIFIER_PROGRESS)) { \
108 	(context)->notifier->progress += (dsofar); \
109 	(context)->notifier->progress_max += (dmax); \
110 	php_stream_notify_progress((context), (context)->notifier->progress, (context)->notifier->progress_max); } } while (0)
111 
112 #define php_stream_notify_file_size(context, file_size, xmsg, xcode) do { if ((context) && (context)->notifier) { \
113 	php_stream_notification_notify((context), PHP_STREAM_NOTIFY_FILE_SIZE_IS, PHP_STREAM_NOTIFY_SEVERITY_INFO, \
114 			(xmsg), (xcode), 0, (file_size), NULL); } } while(0)
115 
116 #define php_stream_notify_error(context, code, xmsg, xcode) do { if ((context) && (context)->notifier) {\
117 	php_stream_notification_notify((context), (code), PHP_STREAM_NOTIFY_SEVERITY_ERR, \
118 			(xmsg), (xcode), 0, 0, NULL); } } while(0)
119