Skip to content
Permalink
Browse files
options: API for meta-data about easy options
 const struct curl_easyoption *curl_easy_option_by_name(const char *name);

 const struct curl_easyoption *curl_easy_option_by_id (CURLoption id);

 const struct curl_easyoption *
 curl_easy_option_next(const struct curl_easyoption *prev);

The purpose is to provide detailed enough information to allow for
example libcurl bindings to get option information at run-time about
what easy options that exist and what arguments they expect.

Assisted-by: Jeroen Ooms
Closes #5365
  • Loading branch information
bagder committed Aug 27, 2020
1 parent 9ee5701 commit 6ebe63fac23f38df911edc348e8ccc72280f9434
Show file tree
Hide file tree
Showing 22 changed files with 1,019 additions and 58 deletions.
@@ -28,6 +28,9 @@ man_MANS = \
curl_easy_escape.3 \
curl_easy_getinfo.3 \
curl_easy_init.3 \
curl_easy_option_by_id.3 \
curl_easy_option_by_name.3 \
curl_easy_option_next.3 \
curl_easy_pause.3 \
curl_easy_perform.3 \
curl_easy_recv.3 \
@@ -0,0 +1,46 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, 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 https://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 curl_easy_option_by_id 3 "15 May 2020" "libcurl 7.71.0" "libcurl Manual"
.SH NAME
curl_easy_option_by_id - find an easy setopt option by id
.SH SYNOPSIS
.nf
#include <curl/curl.h>

const struct curl_easyoption *curl_easy_option_by_id(CURLoption id);
.fi
.SH DESCRIPTION
Given a CURLoption \fBid\fP, this function returns a pointer to the
curl_easyoption struct, holding information about the
\fIcurl_easy_setopt(3)\fP option using that id. The option id is the CURLOPT_
prefix ones provided in the standard curl/curl.h header file. This function
will return the non-aliases version for the cases where there is an alias
function as well.

If libcurl has no option with the given id, this function returns NULL.
.SH AVAILABILITY
This function was added in libcurl 7.71.0
.SH RETURN VALUE
A pointer to the curl_easyoption struct for the option or NULL.
.SH "SEE ALSO"
.BR curl_easy_option_by_name "(3)," curl_easy_option_next "(3),"
.BR curl_easy_setopt "(3),"
@@ -0,0 +1,44 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, 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 https://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 curl_easy_option_by_name 3 "15 May 2020" "libcurl 7.71.0" "libcurl Manual"
.SH NAME
curl_easy_option_by_name - find an easy setopt option by name
.SH SYNOPSIS
.nf
#include <curl/curl.h>

const struct curl_easyoption *curl_easy_option_by_name(const char *name);
.fi
.SH DESCRIPTION
Given a \fBname\fP, this function returns a pointer to the curl_easyoption
struct, holding information about the \fIcurl_easy_setopt(3)\fP option using
that name. The name should be specified without the "CURLOPT_" prefix and the
name comparison is made case insensitive.

If libcurl has no option with the given name, this function returns NULL.
.SH AVAILABILITY
This function was added in libcurl 7.71.0
.SH RETURN VALUE
A pointer to the curl_easyoption struct for the option or NULL.
.SH "SEE ALSO"
.BR curl_easy_option_next "(3)," curl_easy_option_by_id "(3),"
.BR curl_easy_setopt "(3),"
@@ -0,0 +1,74 @@
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2020, 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 https://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 curl_easy_option_next 3 "15 May 2020" "libcurl 7.71.0" "libcurl Manual"
.SH NAME
curl_easy_option_next - iterate over easy setopt options
.SH SYNOPSIS
.nf
#include <curl/curl.h>

typedef enum {
CURLOT_LONG, /* long (a range of values) */
CURLOT_VALUES, /* (a defined set or bitmask) */
CURLOT_OFF_T, /* curl_off_t (a range of values) */
CURLOT_OBJECT, /* pointer (void *) */
CURLOT_STRING, /* (char * to zero terminated buffer) */
CURLOT_SLIST, /* (struct curl_slist *) */
CURLOT_CBPTR, /* (void * passed as-is to a callback) */
CURLOT_BLOB, /* blob (struct curl_blob *) */
CURLOT_FUNCTION /* function pointer */
} curl_easytype;

/* The CURLOPTTYPE_* id ranges can still be used to figure out what type/size
to use for curl_easy_setopt() for the given id */
struct curl_easyoption {
const char *name;
CURLoption id;
curl_easytype type;
unsigned int flags;
};

const struct curl_easyoption *
curl_easy_option_next(const struct curl_easyoption *prev);
.fi
.SH DESCRIPTION
This function returns a pointer to the first or the next curl_easyoption
struct, providing an ability to iterate over all known options for
\fIcurl_easy_setopt(3)\fP in this instance of libcurl.

Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or
pass in the current option to get the next one returned. If there is no more
option to return, \fIcurl_easy_option_next(3)\fP returns NULL.

The options returned by this functions are the ones known to this libcurl and
information about what argument type they want.

If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the
name is provided for backwards compatibility as an alias.
.SH AVAILABILITY
This function was added in libcurl 7.71.0
.SH RETURN VALUE
A pointer to the curl_easyoption struct for the next option or NULL if no more
options.
.SH "SEE ALSO"
.BR curl_easy_option_by_name "(3)," curl_easy_option_by_id "(3),"
.BR curl_easy_setopt "(3),"
@@ -352,12 +352,14 @@ CURLM_UNKNOWN_OPTION 7.15.4
CURLM_WAKEUP_FAILURE 7.68.0
CURLOPT 7.69.0
CURLOPTTYPE_BLOB 7.71.0
CURLOPTTYPE_CBPOINT 7.73.0
CURLOPTTYPE_FUNCTIONPOINT 7.1
CURLOPTTYPE_LONG 7.1
CURLOPTTYPE_OBJECTPOINT 7.1
CURLOPTTYPE_OFF_T 7.11.0
CURLOPTTYPE_SLISTPOINT 7.65.2
CURLOPTTYPE_STRINGPOINT 7.46.0
CURLOPTTYPE_VALUES 7.73.0
CURLOPT_ABSTRACT_UNIX_SOCKET 7.53.0
CURLOPT_ACCEPTTIMEOUT_MS 7.24.0
CURLOPT_ACCEPT_ENCODING 7.21.6
@@ -520,8 +522,6 @@ CURLOPT_PROGRESSDATA 7.1
CURLOPT_PROGRESSFUNCTION 7.1 7.32.0
CURLOPT_PROTOCOLS 7.19.4
CURLOPT_PROXY 7.1
CURLOPT_PROXY_ISSUERCERT 7.71.0
CURLOPT_PROXY_ISSUERCERT_BLOB 7.71.0
CURLOPT_PROXYAUTH 7.10.7
CURLOPT_PROXYHEADER 7.37.0
CURLOPT_PROXYPASSWORD 7.19.1
@@ -532,15 +532,17 @@ CURLOPT_PROXYUSERPWD 7.1
CURLOPT_PROXY_CAINFO 7.52.0
CURLOPT_PROXY_CAPATH 7.52.0
CURLOPT_PROXY_CRLFILE 7.52.0
CURLOPT_PROXY_ISSUERCERT 7.71.0
CURLOPT_PROXY_ISSUERCERT_BLOB 7.71.0
CURLOPT_PROXY_KEYPASSWD 7.52.0
CURLOPT_PROXY_PINNEDPUBLICKEY 7.52.0
CURLOPT_PROXY_SERVICE_NAME 7.43.0
CURLOPT_PROXY_SSLCERT 7.52.0
CURLOPT_PROXY_SSLCERT_BLOB 7.71.0
CURLOPT_PROXY_SSLCERTTYPE 7.52.0
CURLOPT_PROXY_SSLCERT_BLOB 7.71.0
CURLOPT_PROXY_SSLKEY 7.52.0
CURLOPT_PROXY_SSLKEY_BLOB 7.71.0
CURLOPT_PROXY_SSLKEYTYPE 7.52.0
CURLOPT_PROXY_SSLKEY_BLOB 7.71.0
CURLOPT_PROXY_SSLVERSION 7.52.0
CURLOPT_PROXY_SSL_CIPHER_LIST 7.52.0
CURLOPT_PROXY_SSL_OPTIONS 7.52.0
@@ -601,15 +603,15 @@ CURLOPT_SSH_KNOWNHOSTS 7.19.6
CURLOPT_SSH_PRIVATE_KEYFILE 7.16.1
CURLOPT_SSH_PUBLIC_KEYFILE 7.16.1
CURLOPT_SSLCERT 7.1
CURLOPT_SSLCERT_BLOB 7.71.0
CURLOPT_SSLCERTPASSWD 7.1.1 7.17.0
CURLOPT_SSLCERTTYPE 7.9.3
CURLOPT_SSLCERT_BLOB 7.71.0
CURLOPT_SSLENGINE 7.9.3
CURLOPT_SSLENGINE_DEFAULT 7.9.3
CURLOPT_SSLKEY 7.9.3
CURLOPT_SSLKEY_BLOB 7.71.0
CURLOPT_SSLKEYPASSWD 7.9.3 7.17.0
CURLOPT_SSLKEYTYPE 7.9.3
CURLOPT_SSLKEY_BLOB 7.71.0
CURLOPT_SSLVERSION 7.1
CURLOPT_SSL_CIPHER_LIST 7.9
CURLOPT_SSL_CTX_DATA 7.10.6
@@ -667,6 +669,15 @@ CURLOPT_WRITEINFO 7.1
CURLOPT_XFERINFODATA 7.32.0
CURLOPT_XFERINFOFUNCTION 7.32.0
CURLOPT_XOAUTH2_BEARER 7.33.0
CURLOT_BLOB 7.73.0
CURLOT_CBPTR 7.73.0
CURLOT_FUNCTION 7.73.0
CURLOT_LONG 7.73.0
CURLOT_OBJECT 7.73.0
CURLOT_OFF_T 7.73.0
CURLOT_SLIST 7.73.0
CURLOT_STRING 7.73.0
CURLOT_VALUES 7.73.0
CURLPAUSE_ALL 7.18.0
CURLPAUSE_CONT 7.18.0
CURLPAUSE_RECV 7.18.0
@@ -792,9 +803,9 @@ CURLSSLOPT_ALLOW_BEAST 7.25.0
CURLSSLOPT_NATIVE_CA 7.71.0
CURLSSLOPT_NO_PARTIALCHAIN 7.68.0
CURLSSLOPT_NO_REVOKE 7.44.0
CURLSSLOPT_REVOKE_BEST_EFFORT 7.70.0
CURLSSLSET_NO_BACKENDS 7.56.0
CURLSSLSET_OK 7.56.0
CURLSSLOPT_REVOKE_BEST_EFFORT 7.70.0
CURLSSLSET_TOO_LATE 7.56.0
CURLSSLSET_UNKNOWN_BACKEND 7.56.0
CURLUE_BAD_HANDLE 7.62.0
@@ -1007,9 +1018,9 @@ CURL_VERSION_SPNEGO 7.10.8
CURL_VERSION_SSL 7.10
CURL_VERSION_SSPI 7.13.2
CURL_VERSION_TLSAUTH_SRP 7.21.4
CURL_VERSION_UNICODE 7.72.0
CURL_VERSION_UNIX_SOCKETS 7.40.0
CURL_VERSION_ZSTD 7.72.0
CURL_VERSION_UNICODE 7.72.0
CURL_WAIT_POLLIN 7.28.0
CURL_WAIT_POLLOUT 7.28.0
CURL_WAIT_POLLPRI 7.28.0
@@ -5,7 +5,7 @@
# | (__| |_| | _ <| |___
# \___|\___/|_| \_\_____|
#
# Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
# Copyright (C) 1998 - 2020, 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
@@ -21,7 +21,7 @@
###########################################################################
pkginclude_HEADERS = \
curl.h curlver.h easy.h mprintf.h stdcheaders.h multi.h \
typecheck-gcc.h system.h urlapi.h
typecheck-gcc.h system.h urlapi.h options.h

pkgincludedir= $(includedir)/curl

0 comments on commit 6ebe63f

Please sign in to comment.