mirror of
https://github.com/openssl/openssl.git
synced 2024-12-15 06:01:37 +08:00
22fe2b1299
Also improve doc of OSSL_parse_url() and OSSL_HTTP_parse_url(). Reviewed-by: Tomas Mraz <tomas@openssl.org> (Merged from https://github.com/openssl/openssl/pull/15053)
86 lines
3.2 KiB
Plaintext
86 lines
3.2 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
OSSL_parse_url,
|
|
OSSL_HTTP_parse_url,
|
|
OCSP_parse_url
|
|
- http utility functions
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/http.h>
|
|
|
|
int OSSL_parse_url(const char *url, char **pscheme, char **puser, char **phost,
|
|
char **pport, int *pport_num,
|
|
char **ppath, char **pquery, char **pfrag);
|
|
int OSSL_HTTP_parse_url(const char *url,
|
|
int *pssl, char **puser, char **phost,
|
|
char **pport, int *pport_num,
|
|
char **ppath, char **pquery, char **pfrag);
|
|
|
|
Deprecated since OpenSSL 3.0, can be hidden entirely by defining
|
|
B<OPENSSL_API_COMPAT> with a suitable version value, see
|
|
L<openssl_user_macros(7)>:
|
|
|
|
int OCSP_parse_url(const char *url, char **phost, char **pport, char **ppath,
|
|
int *pssl);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
OSSL_parse_url() parses its input string I<url> as a URL of the form
|
|
C<[scheme://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up
|
|
into scheme, userinfo, host, port, path, query, and fragment components.
|
|
The host (or server) component may be a DNS name or an IP address
|
|
where IPv6 addresses should be enclosed in square brackets C<[> and C<]>.
|
|
The port component is optional and defaults to C<0>.
|
|
If given, it must be in decimal form. If the I<pport_num> argument is not NULL
|
|
the integer value of the port number is assigned to I<*pport_num> on success.
|
|
The path component is also optional and defaults to C</>.
|
|
Each non-NULL result pointer argument I<pscheme>, I<puser>, I<phost>, I<pport>,
|
|
I<ppath>, I<pquery>, and I<pfrag>, is assigned the respective url component.
|
|
On success, they are guaranteed to contain non-NULL string pointers, else NULL.
|
|
It is the reponsibility of the caller to free them using L<OPENSSL_free(3)>.
|
|
If I<pquery> is NULL, any given query component is handled as part of the path.
|
|
A string returned via I<*ppath> is guaranteed to begin with a C</> character.
|
|
For absent scheme, userinfo, port, query, and fragment components
|
|
an empty string is provided.
|
|
|
|
OSSL_HTTP_parse_url() is a special form of OSSL_parse_url()
|
|
where the scheme, if given, must be C<http> or C<https>.
|
|
If I<pssl> is not NULL, I<*pssl> is assigned 1 in case parsing was successful
|
|
and the scheme is C<https>, else 0.
|
|
The port component is optional and defaults to C<443> if the scheme is C<https>,
|
|
else C<80>.
|
|
Note that relative paths must be given with a leading C</>,
|
|
otherwise the first path element is interpreted as the hostname.
|
|
|
|
Calling the deprecated function OCSP_parse_url(url, host, port, path, ssl)
|
|
is equivalent to
|
|
OSSL_HTTP_parse_url(url, ssl, NULL, host, port, NULL, path, NULL, NULL).
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
OSSL_parse_url(), OSSL_HTTP_parse_url(), and OCSP_parse_url()
|
|
return 1 on success, 0 on error.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<OSSL_HTTP_transfer(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
OSSL_parse_url() and OSSL_HTTP_parse_url() were added in OpenSSL 3.0.
|
|
OCSP_parse_url() was deprecated in OpenSSL 3.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|