http2: initial HTTP/2 server push types/docs
This commit is contained in:
Daniel Stenberg
Родитель
5156982377
Коммит
70191958b5
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче