include/rtl/uri.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_RTL_URI_H
  25 #define INCLUDED_RTL_URI_H
  26
  27 #include "sal/config.h"
  28
  29 #include "rtl/textenc.h"
  30 #include "rtl/ustring.h"
  31 #include "sal/saldllapi.h"
  32 #include "sal/types.h"
  33
  34 #if defined __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /**  Various predefined URI 'char classes.'
  39
  40      A 'char class' defines which (ASCII) characters can be written 'as they
  41      are' in a part of a Uri, and which characters have to be written using
  42      escape sequences ('%' followed by two hex digits).  Characters outside
  43      the ASCII range are always written using escape sequences.
  44
  45      If there are other frequently used char classes, they can be added to
  46      this enumeration; the function rtl_getUriCharClass() has to be adapted
  47      then, too.
  48  */
  49 typedef enum
  50 {
  51     /** The empty char class.
  52
  53         All characters are written using escape sequences.
  54      */
  55     rtl_UriCharClassNone,
  56
  57     /** The RFC 2732 @<uric> char class.
  58
  59         @verbatim
  60         The 'valid' characters are !$&'()*+,-./:;=?@[]_~ plus digits and
  61         letters.
  62
  63         This differs from RFC 3986 @<fragment> in additionally allowing []
  64         @endverbatim
  65      */
  66     rtl_UriCharClassUric,
  67
  68     /** The RFC 2396 @<uric_no_slash> char class.
  69
  70         @verbatim
  71         The 'valid' characters are !$&'()*+,-.:;=?@_~ plus digits and letters.
  72
  73         This differs from RFC 3986 @<fragment> in additionally encoding /
  74         This differs from RFC 3986 @<pchar> in additionally allowing ?
  75         @endverbatim
  76      */
  77     rtl_UriCharClassUricNoSlash,
  78
  79     /** The RFC 2396 @<rel_segment> char class.
  80
  81         @verbatim
  82         The 'valid' characters are !$&'()*+,-.;=@_~ plus digits and letters.
  83
  84         This is the same as RFC 3986 @<segment-nz-nc>
  85         @endverbatim
  86      */
  87     rtl_UriCharClassRelSegment,
  88
  89     /** The RFC 2396 @<reg_name> char class.
  90
  91         @verbatim
  92         The 'valid' characters are !$&'()*+,-.:;=@_~ plus digits and letters.
  93
  94         This differs from RFC 3986 @<reg_name> in additionally allowing @
  95         @endverbatim
  96      */
  97     rtl_UriCharClassRegName,
  98
  99     /** The RFC 2396 @<userinfo> char class.
 100
 101         @verbatim
 102         The 'valid' characters are !$&'()*+,-.:;=_~ plus digits and letters.
 103
 104         This is the same as RFC 3986 @<userinfo>
 105         @endverbatim
 106      */
 107     rtl_UriCharClassUserinfo,
 108
 109     /** The RFC 2396 @<pchar> char class.
 110
 111         @verbatim
 112         The 'valid' characters are !$&'()*+,-.:=@_~ plus digits and letters.
 113
 114         This differs from RFC 3986 @<pchar> in additionally encoding ;
 115         @endverbatim
 116      */
 117     rtl_UriCharClassPchar,
 118
 119     /** The char class for the values of uno URL parameters.
 120
 121         @verbatim
 122         The 'valid' characters are !$&'()*+-./:?@_~ plus digits and letters.
 123         @endverbatim
 124      */
 125     rtl_UriCharClassUnoParamValue,
 126
 127     rtl_UriCharClass_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 128 }
 129 rtl_UriCharClass;
 130
 131 /** The mechanism describing how escape sequences in the input of
 132     rtl_uriEncode() are handled.
 133  */
 134 typedef enum
 135 {
 136     /** The special meaning of '%' is ignored (i.e., there are by definition
 137         no escape sequences in the input).
 138
 139         This mechanism is useful to encode user input as part of a URI (e.g.,
 140         the user-supplied password in an ftp URL---'%20abcde' is a valid
 141         password, so do not assume that the '%20' is an escaped space).
 142      */
 143     rtl_UriEncodeIgnoreEscapes,
 144
 145     /** All escape sequences ('%' followed by two hex digits) are kept intact,
 146         even if they represent characters that need not be escaped or if they
 147         do not even map to characters in the given charset.
 148
 149         This mechanism is useful when passing on complete URIs more or less
 150         unmodified (e.g., within an HTTP proxy): missing escape sequences are
 151         added, but existing escape sequences are not touched (except that any
 152         lower case hex digits are replaced by upper case hex digits).
 153      */
 154     rtl_UriEncodeKeepEscapes,
 155
 156     /** All escape sequences ('%' followed by two hex digits) are resolved in
 157         a first step; only those that represent characters that need to be
 158         escaped are kept intact.
 159
 160         This mechanism is useful to properly encode complete URIs entered by
 161         the user: the URI is brought into a 'canonic form,' but care is taken
 162         not to damage (valid) escape sequences the (careful) user already
 163         entered as such.
 164      */
 165     rtl_UriEncodeCheckEscapes,
 166
 167     /** Like rtl_UriEncodeIgnoreEscapes, but indicating failure when converting
 168         unmappable characters.
 169
 170         @since UDK 3.2.0
 171      */
 172     rtl_UriEncodeStrict,
 173
 174     /** Like rtl_UriEncodeKeepEscapes, but indicating failure when converting
 175         unmappable characters.
 176
 177         @since UDK 3.2.7
 178      */
 179     rtl_UriEncodeStrictKeepEscapes,
 180
 181     rtl_UriEncode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 182 }
 183 rtl_UriEncodeMechanism;
 184
 185 /** The mechanism describing how rtl_uriDecode() translates (part of) a URI
 186     into a Unicode string.
 187  */
 188 typedef enum
 189 {
 190     /** The text is returned completely unmodified.
 191      */
 192     rtl_UriDecodeNone,
 193
 194     /** The text is returned in the form of an IURI (cf.
 195         draft-masinter-url-i18n-05.txt).
 196
 197         All escape sequences representing ASCII characters (%00--%7F) are
 198         kept, all other escape sequences are interpreted as UTF-8 characters
 199         and translated to Unicode, if possible.
 200      */
 201     rtl_UriDecodeToIuri,
 202
 203     /** The text is decoded.
 204
 205         All escape sequences representing characters from the given charset
 206         are decoded and translated to Unicode, if possible.
 207      */
 208     rtl_UriDecodeWithCharset,
 209
 210     /** Like rtl_UriDecodeWithCharset, but indicating failure when converting
 211         unmappable characters.
 212
 213         @since UDK 3.2.0
 214      */
 215     rtl_UriDecodeStrict,
 216
 217     rtl_UriDecode_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 218 }
 219 rtl_UriDecodeMechanism;
 220
 221 /** Map a predefined rtl_UriCharClass to a form usable by rtl_uriEncode().
 222
 223     The function rtl_uriEncode() expects an array of 128 booleans, and this
 224     function maps rtl_UriCharClass enumeration members to such arrays.
 225
 226     @param eCharClass
 227     Any valid member of rtl_UriCharClass.
 228
 229     @return
 230     An array of 128 booleans, to be used in calls to rtl_uriEncode().
 231  */
 232 SAL_DLLPUBLIC sal_Bool const * SAL_CALL rtl_getUriCharClass(rtl_UriCharClass eCharClass)
 233     SAL_THROW_EXTERN_C();
 234
 235 /** Encode a text as (part of) a URI.
 236
 237     @param pText
 238     Any Unicode string.  Must not be null.
 239
 240     @param pCharClass
 241     A char class, represented as an array of 128 booleans (true means keep the
 242     corresponding ASCII character unencoded, false means encode it).  Must not
 243     be null, and the boolean corresponding to the percent sign (0x25) must be
 244     false.  (See rtl_getUriCharClass() for a function mapping from
 245     rtl_UriCharClass to such arrays.)
 246
 247     @param eMechanism
 248     The mechanism describing how escape sequences in the input text are
 249     handled.
 250
 251     @param eCharset
 252     When Unicode characters from the input text have to be written using
 253     escape sequences (because they are either outside the ASCII range or do
 254     not belong to the given char class), they are first translated into this
 255     charset before being encoded using escape sequences.
 256
 257     Also, if the encode mechanism is rtl_UriEncodeCheckEscapes, all escape
 258     sequences already present in the input text are interpreted as characters
 259     from this charset.
 260
 261     @param pResult
 262     Returns an encoded representation of the input text.  Must itself not be
 263     null, and must point to either null or a valid string.
 264
 265     If the encode mechanism is rtl_UriEncodeStrict, and pText cannot be
 266     converted to eCharset because it contains unmappable characters (which
 267     implies that pText is not empty), then an empty string is returned.
 268  */
 269 SAL_DLLPUBLIC void SAL_CALL rtl_uriEncode(
 270                             rtl_uString * pText,
 271                             sal_Bool const * pCharClass,
 272                             rtl_UriEncodeMechanism eMechanism,
 273                             rtl_TextEncoding eCharset,
 274                             rtl_uString ** pResult)
 275     SAL_THROW_EXTERN_C();
 276
 277 /** Decode (a part of) a URI.
 278
 279     @param pText
 280     Any Unicode string.  Must not be null.  (If the input is indeed part of a
 281     valid URI, this string will only contain a subset of the ASCII characters,
 282     but this function also handles other Unicode characters properly.)
 283
 284     @param eMechanism
 285     The mechanism describing how the input text is translated into a Unicode
 286     string.
 287
 288     @param eCharset
 289     When the decode mechanism is rtl_UriDecodeWithCharset, all escape
 290     sequences in the input text are interpreted as characters from this
 291     charset.  Those characters are translated to Unicode characters in the
 292     resulting output, if possible.
 293
 294     When the decode mechanism is rtl_UriDecodeNone or rtl_UriDecodeToIuri,
 295     this parameter is ignored (and is best specified as
 296     RTL_TEXTENCODING_UTF8).
 297
 298     @param pResult
 299     Returns a decoded representation of the input text.  Must itself not be
 300     null, and must point to either null or a valid string.
 301
 302     If the decode mechanism is rtl_UriDecodeStrict, and pText cannot be
 303     converted to eCharset because it contains (encodings of) unmappable
 304     characters (which implies that pText is not empty), then an empty string is
 305     returned.
 306  */
 307 SAL_DLLPUBLIC void SAL_CALL rtl_uriDecode(
 308                             rtl_uString * pText,
 309                             rtl_UriDecodeMechanism eMechanism,
 310                             rtl_TextEncoding eCharset,
 311                             rtl_uString ** pResult)
 312     SAL_THROW_EXTERN_C();
 313
 314 /** Convert a relative URI reference into an absolute URI.
 315
 316     This function uses the strict parser algorithm described in RFC 3986,
 317     section 5.2.
 318
 319     This function signals exceptions by returning false and letting pException
 320     point to a message explaining the exception.
 321
 322     @param pBaseUriRef
 323     An absolute URI that serves as the base URI.  If it has to be inspected
 324     (i.e., pRelUriRef is not an absolute URI already), and it is not an absolute
 325     URI (i.e., does not begin with a @<scheme ":"> part), an exception will be
 326     signaled.
 327
 328     @param pRelUriRef
 329     A URI reference that may be either absolute or relative.  If it is
 330     absolute, it will be returned unmodified.
 331
 332     @param pResult
 333     Returns an absolute URI.  Must itself not be null, and must point to either
 334     null or a valid string.  If an exception is signalled, it is left unchanged.
 335
 336     @param pException
 337     Returns an explanatory message in case an exception is signalled.  Must
 338     itself not be null, and must point to either null or a valid string.  If no
 339     exception is signalled, it is left unchanged.
 340
 341     @return
 342     True if no exception is signalled, otherwise false.
 343  */
 344 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_uriConvertRelToAbs(
 345                                          rtl_uString * pBaseUriRef,
 346                                          rtl_uString * pRelUriRef,
 347                                          rtl_uString ** pResult,
 348                                          rtl_uString ** pException)
 349     SAL_THROW_EXTERN_C();
 350
 351 #if defined __cplusplus
 352 }
 353 #endif /* __cplusplus */
 354
 355 #endif // INCLUDED_RTL_URI_H
 356
 357 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */