[vlc-devel] commit: decode_URI: improve documentation, add a return value ( Rémi Denis-Courmont )

[git version control]

vlc | branch: 1.0-bugfix | Rémi Denis-Courmont <remi at remlab.net> | Sun May 10 13:35:56 2009 +0300| [d04effdcbb9208faf7fbcd9cf828ab51f3df2f50] | committer: Rémi Denis-Courmont 

decode_URI: improve documentation, add a return value

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=d04effdcbb9208faf7fbcd9cf828ab51f3df2f50
---

 include/vlc_url.h  |    2 +-
 src/text/strings.c |   24 +++++++++++++++++-------
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/include/vlc_url.h b/include/vlc_url.h
index dc2a021..271e4d2 100644
--- a/include/vlc_url.h
+++ b/include/vlc_url.h
@@ -48,7 +48,7 @@ struct vlc_url_t
 VLC_EXPORT( char *, unescape_URI_duplicate, ( const char *psz ) );
 VLC_EXPORT( void, unescape_URI, ( char *psz ) );
 VLC_EXPORT( char *, decode_URI_duplicate, ( const char *psz ) );
-VLC_EXPORT( void, decode_URI, ( char *psz ) );
+VLC_EXPORT( char *, decode_URI, ( char *psz ) );
 VLC_EXPORT( char *, encode_URI_component, ( const char *psz ) );
 
 /*****************************************************************************
diff --git a/src/text/strings.c b/src/text/strings.c
index 8a0229c..4eea72f 100644
--- a/src/text/strings.c
+++ b/src/text/strings.c
@@ -130,7 +130,7 @@ void unescape_URI( char *psz )
 }
 
 /**
- * Decode encoded URI string
+ * Decode encoded URI component. See also decode_URI().
  * \return decoded duplicated string
  */
 char *decode_URI_duplicate( const char *psz )
@@ -141,14 +141,23 @@ char *decode_URI_duplicate( const char *psz )
 }
 
 /**
- * Decode encoded URI string in place
- * \return nothing
+ * Decode an encoded URI component in place.
+ * <b>This function does NOT decode entire URIs.</b>
+ * It decodes components (e.g. host name, directory, file name).
+ * Decoded URIs do not exist in the real world (see RFC3986 §2.4).
+ * Complete URIs are always "encoded" (or they are syntaxically invalid).
+ *
+ * Note that URI encoding is different from Javascript escaping. Especially,
+ * white spaces and Unicode non-ASCII code points are encoded differently.
+ *
+ * \return psz on success, NULL if it was not properly encoded
  */
-void decode_URI( char *psz )
+char *decode_URI( char *psz )
 {
     unsigned char *in = (unsigned char *)psz, *out = in, c;
+
     if( psz == NULL )
-        return;
+        return NULL;
 
     while( ( c = *in++ ) != '\0' )
     {
@@ -160,14 +169,14 @@ void decode_URI( char *psz )
 
                 if( ( ( hex[0] = *in++ ) == 0 )
                  || ( ( hex[1] = *in++ ) == 0 ) )
-                    return;
+                    return NULL;
 
                 hex[2] = '\0';
                 *out++ = (unsigned char)strtoul( hex, NULL, 0x10 );
                 break;
             }
 
-            case '+':
+            case '+': /* This is HTTP forms, not URI decoding... */
                 *out++ = ' ';
                 break;
 
@@ -182,6 +191,7 @@ void decode_URI( char *psz )
     }
     *out = '\0';
     EnsureUTF8( psz );
+    return psz;
 }
 
 static inline bool isurisafe( int c )