diff options
| -rw-r--r-- | docs/libcurl/opts/CURLMOPT_PUSHDATA.3 | 49 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 | 108 | ||||
| -rw-r--r-- | docs/libcurl/opts/Makefile.am | 8 | ||||
| -rw-r--r-- | include/curl/multi.h | 32 |
4 files changed, 194 insertions, 3 deletions
diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 new file mode 100644 index 000000000..135e63212 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLMOPT_PUSHDATA 3 "1 Jun 2015" "libcurl 7.44.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_PUSHDATA \- pointer to pass to push callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHDATA, void *pointer); +.fi +.SH DESCRIPTION +Set \fIpointer\fP to pass as the last argument to the +\fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer will not be touched or +used by libcurl itself, only passed on to the callback function. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.44.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PUSHFUNCTION "(3), " CURLMOPT_PIPELINING "(3), " +.BR CURLOPT_PIPEWAIT "(3), " +.BR RFC 7540 diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 new file mode 100644 index 000000000..28fa2e76c --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 @@ -0,0 +1,108 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLMOPT_PUSHFUNCTION 3 "1 Jun 2015" "libcurl 7.44.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_PUSHFUNCTION \- approve or deny server pushes +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +struct curl_headerpair { + unsigned char *name; /* zero terminated name */ + size_t namelen; /* length of 'name' */ + unsigned char *value; /* zero terminated name */ + size_t valuelen; /* length of 'value' */ +}; + +struct curl_headerpair *curl_pushheader_bynum(push_headers, int num); +struct curl_headerpair *curl_pushheader_byname(push_headers, char *name); + +int curl_push_callback(CURL *parent, + CURL *easy, + int num_headers, + struct curl_pushheaders *headers, + void *userp); + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PUSHFUNCTION, + curl_push_callback func); +.fi +.SH DESCRIPTION +This callback gets called when a new HTTP/2 stream is being pushed by the +server (using the PUSH_PROMISE frame). If no push callback is set, all offered +pushes will be denied automatically. +.SH CALLBACK DESCRIPTION +The callback gets its arguments like this: + +\fIeasy\fP is a newly created handle that represents this new transfer. + +\fIparent\fP is the handle of the stream on which this push arrives. The new +handle has been duphandle()d from the parent, meaning that it has gotten all +its options inherited. It is then up to the application to alter any options +if desired. + +\fInum_headers\fP is the number of name+value pairs that was received and can +be accessed + +\fIheaders\fP is a handle used to access push headers using the accessor +functions described below. This only accesses and provides the PUSH_PROMISE +headers, the normal response headers will be provided in the header callback +as usual. + +\fIuserp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP + +If the callback returns CURL_PUSH_OK, the 'easy' handle will be added to the +multi handle, the callback must not do that by itself. + +The callback can access PUSH_PROMISE headers with two accessor +functions. These functions can only be used from within this callback and they +can only access the PUSH_PROMISE headers. The normal response headers will be +pased to the header callback for pushed streams just as for normal streams. +.IP curl_pushheader_bynum +Returns the header pair at index 'num' (or NULL). The returned pointer points +to a struct that will be freed when this callback returns. +.IP curl_pushheader_byname +Returns the header pair for the given header name (or NULL). This is a +shortcut so that the application doesn't have to loop through all headers to +find the one it is interested in. +.SH CALLBACK RETURN VALUE +.IP "CURL_PUSH_OK (0)" +The application has accepted the stream and it can now start receiving data, +the ownership of the CURL handle has been taken over by the application. +.IP "CURL_PUSH_DENY (1)" +The callback denies the stream and no data for this will reach the +application, the easy handle will be destroyed by libcurl. +.IP * +All other return codes are reserved for future use. +.SH DEFAULT +NULL, no callback +.SH PROTOCOLS +HTTP(S) (HTTP/2 only) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.44.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PUSHDATA "(3), " CURLMOPT_PIPELINING "(3), " CURLOPT_PIPEWAIT "(3), " +.BR RFC 7540 diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 5517811d0..4865b41b5 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -114,7 +114,8 @@ man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3 \ CURLMOPT_SOCKETDATA.3 CURLMOPT_SOCKETFUNCTION.3 CURLMOPT_TIMERDATA.3 \ CURLMOPT_TIMERFUNCTION.3 CURLOPT_UNIX_SOCKET_PATH.3 \ CURLOPT_PATH_AS_IS.3 CURLOPT_PROXY_SERVICE_NAME.3 \ - CURLOPT_SERVICE_NAME.3 CURLOPT_PIPEWAIT.3 + CURLOPT_SERVICE_NAME.3 CURLOPT_PIPEWAIT.3 CURLMOPT_PUSHDATA.3 \ + CURLMOPT_PUSHFUNCTION.3 HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \ CURLOPT_ADDRESS_SCOPE.html CURLOPT_APPEND.html \ @@ -222,7 +223,8 @@ HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \ CURLMOPT_TIMERDATA.html CURLMOPT_TIMERFUNCTION.html \ CURLOPT_UNIX_SOCKET_PATH.html CURLOPT_PATH_AS_IS.html \ CURLOPT_PROXY_SERVICE_NAME.html CURLOPT_SERVICE_NAME.html \ - CURLOPT_PIPEWAIT.html + CURLOPT_PIPEWAIT.html CURLMOPT_PUSHDATA.html \ + CURLMOPT_PUSHFUNCTION.html PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \ CURLOPT_ADDRESS_SCOPE.pdf CURLOPT_APPEND.pdf CURLOPT_AUTOREFERER.pdf \ @@ -328,7 +330,7 @@ PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \ CURLMOPT_TIMERDATA.pdf CURLMOPT_TIMERFUNCTION.pdf \ CURLOPT_UNIX_SOCKET_PATH.pdf CURLOPT_PATH_AS_IS.pdf \ CURLOPT_PROXY_SERVICE_NAME.pdf CURLOPT_SERVICE_NAME.pdf \ - CURLOPT_PIPEWAIT.pdf + CURLOPT_PIPEWAIT.pdf CURLMOPT_PUSHDATA.pdf CURLMOPT_PUSHFUNCTION.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/include/curl/multi.h b/include/curl/multi.h index 0d859f8fd..ed3a3a793 100644 --- a/include/curl/multi.h +++ b/include/curl/multi.h @@ -283,6 +283,32 @@ typedef int (*curl_multi_timer_callback)(CURLM *multi, /* multi handle */ void *userp); /* private callback pointer */ +/* + * Name: curl_push_callback + * + * Desc: This callback gets called when a new stream is being pushed by the + * server. It approves or denies the new stream. + * + * Returns: CURL_PUSH_OK or CURL_PUSH_DENY. + */ +#define CURL_PUSH_OK 0 +#define CURL_PUSH_DENY 1 + +struct curl_headerpair { + unsigned char *name; /* zero terminated name */ + size_t namelen; /* length of 'name' */ + unsigned char *value; /* zero terminated name */ + size_t valuelen; /* length of 'value' */ +}; + +struct curl_pushheaders; /* forward declaration only */ + +typedef int (*curl_push_callback)(CURL *parent, + CURL *easy, + int num_headers, + struct curl_pushheaders *headers, + void *userp); + CURL_EXTERN CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t s, int *running_handles); @@ -370,6 +396,12 @@ typedef enum { /* maximum number of open connections in total */ CINIT(MAX_TOTAL_CONNECTIONS, LONG, 13), + /* This is the server push callback function pointer */ + CINIT(PUSHFUNCTION, FUNCTIONPOINT, 14), + + /* This is the argument passed to the server push callback */ + CINIT(PUSHDATA, OBJECTPOINT, 15), + CURLMOPT_LASTENTRY /* the last unused */ } CURLMoption; |