mirror of
https://github.com/netsurf-browser/netsurf
synced 2024-11-28 17:23:09 +03:00
295 lines
8.7 KiB
C
295 lines
8.7 KiB
C
/*
|
|
* Copyright 2011 Michael Drake <tlsa@netsurf-browser.org>
|
|
*
|
|
* This file is part of NetSurf, http://www.netsurf-browser.org/
|
|
*
|
|
* NetSurf is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; version 2 of the License.
|
|
*
|
|
* NetSurf is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/** \file
|
|
* NetSurf URL handling (interface).
|
|
*/
|
|
|
|
#ifndef _NETSURF_UTILS_NSURL_H_
|
|
#define _NETSURF_UTILS_NSURL_H_
|
|
|
|
#include <libwapcaplet/libwapcaplet.h>
|
|
#include "utils/errors.h"
|
|
|
|
|
|
/** NetSurf URL object */
|
|
typedef struct nsurl nsurl;
|
|
|
|
|
|
typedef enum nsurl_component {
|
|
NSURL_SCHEME = (1 << 0),
|
|
NSURL_USERNAME = (1 << 1),
|
|
NSURL_PASSWORD = (1 << 2),
|
|
NSURL_CREDENTIALS = NSURL_USERNAME | NSURL_PASSWORD,
|
|
NSURL_HOST = (1 << 3),
|
|
NSURL_PORT = (1 << 4),
|
|
NSURL_AUTHORITY = NSURL_CREDENTIALS | NSURL_HOST | NSURL_PORT,
|
|
NSURL_PATH = (1 << 5),
|
|
NSURL_QUERY = (1 << 6),
|
|
NSURL_COMPLETE = NSURL_SCHEME | NSURL_AUTHORITY |
|
|
NSURL_PATH | NSURL_QUERY,
|
|
NSURL_FRAGMENT = (1 << 7),
|
|
NSURL_WITH_FRAGMENT = NSURL_COMPLETE | NSURL_FRAGMENT
|
|
} nsurl_component;
|
|
|
|
|
|
/**
|
|
* Create a NetSurf URL object from a URL string
|
|
*
|
|
* \param url_s String to create NetSurf URL from
|
|
* \param url Returns a NetSurf URL
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in url.
|
|
*
|
|
* It is up to the client to call nsurl_destroy when they are finished with
|
|
* the created object.
|
|
*/
|
|
nserror nsurl_create(const char * const url_s, nsurl **url);
|
|
|
|
|
|
/**
|
|
* Increment the reference count to a NetSurf URL object
|
|
*
|
|
* \param url NetSurf URL to create another reference to
|
|
* \return The NetSurf URL pointer to use as the copy
|
|
*
|
|
* Use this when copying a NetSurf URL into a persistent data structure.
|
|
*/
|
|
nsurl *nsurl_ref(nsurl *url);
|
|
|
|
|
|
/**
|
|
* Drop a reference to a NetSurf URL object
|
|
*
|
|
* \param url NetSurf URL to drop reference to
|
|
*
|
|
* When the reference count reaches zero then the NetSurf URL will be destroyed
|
|
*/
|
|
void nsurl_unref(nsurl *url);
|
|
|
|
|
|
/**
|
|
* Compare two URLs
|
|
*
|
|
* \param url1 First NetSurf URL
|
|
* \param url2 Second NetSurf URL
|
|
* \param parts The URL components to be compared
|
|
* \param match Returns true if url1 and url2 matched, else false
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, match will be false.
|
|
*/
|
|
bool nsurl_compare(const nsurl *url1, const nsurl *url2, nsurl_component parts);
|
|
|
|
|
|
/**
|
|
* Get URL (section) as a string, from a NetSurf URL object
|
|
*
|
|
* \param url NetSurf URL
|
|
* \param parts The required URL components.
|
|
* \param url_s Returns a url string
|
|
* \param url_l Returns length of url_s
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in url_s or url_l.
|
|
*
|
|
* The string returned in url_s is owned by the client and it is up to them
|
|
* to free it. It includes a trailing '\0'.
|
|
*
|
|
* The length returned in url_l excludes the trailing '\0'.
|
|
*
|
|
* That the required URL components be consecutive is not enforced, however,
|
|
* non-consecutive URL components generally make no sense. The exception
|
|
* is removal of credentials from a URL, such as for display in browser
|
|
* window URL bar. 'NSURL_COMPLETE &~ NSURL_PASSWORD' would remove the
|
|
* password from a complete URL.
|
|
*/
|
|
nserror nsurl_get(const nsurl *url, nsurl_component parts,
|
|
char **url_s, size_t *url_l);
|
|
|
|
|
|
/**
|
|
* Get part of a URL as a lwc_string, from a NetSurf URL object
|
|
*
|
|
* \param url NetSurf URL object
|
|
* \param part The URL component required
|
|
* \return the required component as an lwc_string, or NULL
|
|
*
|
|
* The caller owns the returned lwc_string and should call lwc_string_unref
|
|
* when they are done with it.
|
|
*
|
|
* The valid values for the part parameter are:
|
|
* NSURL_SCHEME
|
|
* NSURL_USERNAME
|
|
* NSURL_PASSWORD
|
|
* NSURL_HOST
|
|
* NSURL_PORT
|
|
* NSURL_PATH
|
|
* NSURL_QUERY
|
|
* NSURL_FRAGMENT
|
|
*/
|
|
lwc_string *nsurl_get_component(const nsurl *url, nsurl_component part);
|
|
|
|
|
|
/**
|
|
* Enquire about the existence of componenets in a given URL
|
|
*
|
|
* \param url NetSurf URL object
|
|
* \param part The URL components confirm existence of
|
|
* \return true iff the component in question exists in url
|
|
*
|
|
* The valid values for the part parameter are:
|
|
* NSURL_SCHEME
|
|
* NSURL_USERNAME
|
|
* NSURL_PASSWORD
|
|
* NSURL_CREDENTIALS
|
|
* NSURL_HOST
|
|
* NSURL_PORT
|
|
* NSURL_PATH
|
|
* NSURL_QUERY
|
|
* NSURL_FRAGMENT
|
|
*/
|
|
bool nsurl_has_component(const nsurl *url, nsurl_component part);
|
|
|
|
|
|
/**
|
|
* Access a NetSurf URL object as a string
|
|
*
|
|
* \param url NetSurf URL to retrieve a string pointer for.
|
|
* \return the required string
|
|
*
|
|
* The returned string is owned by the NetSurf URL object. It will die
|
|
* with the NetSurf URL object. Keep a reference to the URL if you need it.
|
|
*
|
|
* The returned string has a trailing '\0'.
|
|
*/
|
|
const char *nsurl_access(const nsurl *url);
|
|
|
|
|
|
/**
|
|
* Access a URL's path leaf as a string
|
|
*
|
|
* \param url NetSurf URL to retrieve a string pointer for.
|
|
* \return the required string
|
|
*
|
|
* The returned string is owned by the NetSurf URL object. It will die
|
|
* with the NetSurf URL object. Keep a reference to the URL if you need it.
|
|
*
|
|
* The returned string has a trailing '\0'.
|
|
*/
|
|
const char *nsurl_access_leaf(const nsurl *url);
|
|
|
|
|
|
/**
|
|
* Find the length of a NetSurf URL object's URL, as returned by nsurl_access
|
|
*
|
|
* \param url NetSurf URL to find length of.
|
|
* \return the required string
|
|
*
|
|
* The returned length excludes the trailing '\0'.
|
|
*/
|
|
size_t nsurl_length(const nsurl *url);
|
|
|
|
|
|
/**
|
|
* Join a base url to a relative link part, creating a new NetSurf URL object
|
|
*
|
|
* \param base NetSurf URL containing the base to join rel to
|
|
* \param rel String containing the relative link part
|
|
* \param joined Returns joined NetSurf URL
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in join.
|
|
*
|
|
* It is up to the client to call nsurl_destroy when they are finished with
|
|
* the created object.
|
|
*/
|
|
nserror nsurl_join(const nsurl *base, const char *rel, nsurl **joined);
|
|
|
|
|
|
/**
|
|
* Create a NetSurf URL object without a fragment from a NetSurf URL
|
|
*
|
|
* \param url NetSurf URL to create new NetSurf URL from
|
|
* \param no_frag Returns new NetSurf URL without fragment
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in no_frag.
|
|
*
|
|
* It is up to the client to call nsurl_destroy when they are finished with
|
|
* the created object.
|
|
*/
|
|
nserror nsurl_defragment(const nsurl *url, nsurl **no_frag);
|
|
|
|
|
|
/**
|
|
* Create a NetSurf URL object, adding a fragment to an existing URL object
|
|
*
|
|
* \param url NetSurf URL to create new NetSurf URL from
|
|
* \param frag Fragment to add
|
|
* \param new_url Returns new NetSurf URL without fragment
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in new_url.
|
|
*
|
|
* It is up to the client to call nsurl_destroy when they are finished with
|
|
* the created object.
|
|
*
|
|
* Any fragment in url is replaced with frag in new_url.
|
|
*/
|
|
nserror nsurl_refragment(const nsurl *url, lwc_string *frag, nsurl **new_url);
|
|
|
|
|
|
/**
|
|
* Create a NetSurf URL object, with query string replaced
|
|
*
|
|
* \param url NetSurf URL to create new NetSurf URL from
|
|
* \param query Query string to use
|
|
* \param new_url Returns new NetSurf URL with query string provided
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in new_url.
|
|
*
|
|
* It is up to the client to call nsurl_destroy when they are finished with
|
|
* the created object.
|
|
*
|
|
* Any query component in url is replaced with query in new_url.
|
|
*/
|
|
nserror nsurl_replace_query(const nsurl *url, const char *query,
|
|
nsurl **new_url);
|
|
|
|
|
|
/**
|
|
* Create a NetSurf URL object for URL with parent location of an existing URL.
|
|
*
|
|
* \param url NetSurf URL to create new NetSurf URL from
|
|
* \param new_url Returns new NetSurf URL with parent URL path
|
|
* \return NSERROR_OK on success, appropriate error otherwise
|
|
*
|
|
* If return value != NSERROR_OK, nothing will be returned in new_url.
|
|
*
|
|
* It is up to the client to call nsurl_destroy when they are finished with
|
|
* the created object.
|
|
*
|
|
* As well as stripping top most path segment, query and fragments are stripped.
|
|
*/
|
|
nserror nsurl_parent(const nsurl *url, nsurl **new_url);
|
|
|
|
#endif
|