sal/inc/rtl/uri.h

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