1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.URI;
26 
27 private import glib.ErrorG;
28 private import glib.GException;
29 private import glib.Str;
30 private import gtkc.glib;
31 public  import gtkc.glibtypes;
32 
33 
34 /** */
35 public struct URI
36 {
37 
38 	/**
39 	 * Converts an escaped ASCII-encoded URI to a local filename in the
40 	 * encoding used for filenames.
41 	 *
42 	 * Params:
43 	 *     uri = a uri describing a filename (escaped, encoded in ASCII).
44 	 *     hostname = Location to store hostname for the
45 	 *         URI.
46 	 *         If there is no hostname in the URI, %NULL will be
47 	 *         stored in this location.
48 	 *
49 	 * Return: a newly-allocated string holding
50 	 *     the resulting filename, or %NULL on an error.
51 	 *
52 	 * Throws: GException on failure.
53 	 */
54 	public static string filenameFromUri(string uri, out string hostname)
55 	{
56 		char* outhostname = null;
57 		GError* err = null;
58 		
59 		auto retStr = g_filename_from_uri(Str.toStringz(uri), &outhostname, &err);
60 		
61 		if (err !is null)
62 		{
63 			throw new GException( new ErrorG(err) );
64 		}
65 		
66 		hostname = Str.toString(outhostname);
67 		
68 		scope(exit) Str.freeString(retStr);
69 		return Str.toString(retStr);
70 	}
71 
72 	/**
73 	 * Converts an absolute filename to an escaped ASCII-encoded URI, with the path
74 	 * component following Section 3.3. of RFC 2396.
75 	 *
76 	 * Params:
77 	 *     filename = an absolute filename specified in the GLib file
78 	 *         name encoding, which is the on-disk file name bytes on Unix, and UTF-8
79 	 *         on Windows
80 	 *     hostname = A UTF-8 encoded hostname, or %NULL for none.
81 	 *
82 	 * Return: a newly-allocated string holding the resulting
83 	 *     URI, or %NULL on an error.
84 	 *
85 	 * Throws: GException on failure.
86 	 */
87 	public static string filenameToUri(string filename, string hostname)
88 	{
89 		GError* err = null;
90 		
91 		auto retStr = g_filename_to_uri(Str.toStringz(filename), Str.toStringz(hostname), &err);
92 		
93 		if (err !is null)
94 		{
95 			throw new GException( new ErrorG(err) );
96 		}
97 		
98 		scope(exit) Str.freeString(retStr);
99 		return Str.toString(retStr);
100 	}
101 
102 	/**
103 	 * Escapes a string for use in a URI.
104 	 *
105 	 * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
106 	 * characters plus dash, dot, underscore and tilde) are escaped.
107 	 * But if you specify characters in @reserved_chars_allowed they are not
108 	 * escaped. This is useful for the "reserved" characters in the URI
109 	 * specification, since those are allowed unescaped in some portions of
110 	 * a URI.
111 	 *
112 	 * Params:
113 	 *     unescaped = the unescaped input string.
114 	 *     reservedCharsAllowed = a string of reserved characters that
115 	 *         are allowed to be used, or %NULL.
116 	 *     allowUtf8 = %TRUE if the result can include UTF-8 characters.
117 	 *
118 	 * Return: an escaped version of @unescaped. The returned string should be
119 	 *     freed when no longer needed.
120 	 *
121 	 * Since: 2.16
122 	 */
123 	public static string uriEscapeString(string unescaped, string reservedCharsAllowed, bool allowUtf8)
124 	{
125 		auto retStr = g_uri_escape_string(Str.toStringz(unescaped), Str.toStringz(reservedCharsAllowed), allowUtf8);
126 		
127 		scope(exit) Str.freeString(retStr);
128 		return Str.toString(retStr);
129 	}
130 
131 	/**
132 	 * Splits an URI list conforming to the text/uri-list
133 	 * mime type defined in RFC 2483 into individual URIs,
134 	 * discarding any comments. The URIs are not validated.
135 	 *
136 	 * Params:
137 	 *     uriList = an URI list
138 	 *
139 	 * Return: a newly allocated %NULL-terminated list
140 	 *     of strings holding the individual URIs. The array should be freed
141 	 *     with g_strfreev().
142 	 *
143 	 * Since: 2.6
144 	 */
145 	public static string[] uriListExtractUris(string uriList)
146 	{
147 		auto retStr = g_uri_list_extract_uris(Str.toStringz(uriList));
148 		
149 		scope(exit) Str.freeStringArray(retStr);
150 		return Str.toStringArray(retStr);
151 	}
152 
153 	/**
154 	 * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
155 	 * |[
156 	 * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
157 	 * ]|
158 	 * Common schemes include "file", "http", "svn+ssh", etc.
159 	 *
160 	 * Params:
161 	 *     uri = a valid URI.
162 	 *
163 	 * Return: The "Scheme" component of the URI, or %NULL on error.
164 	 *     The returned string should be freed when no longer needed.
165 	 *
166 	 * Since: 2.16
167 	 */
168 	public static string uriParseScheme(string uri)
169 	{
170 		auto retStr = g_uri_parse_scheme(Str.toStringz(uri));
171 		
172 		scope(exit) Str.freeString(retStr);
173 		return Str.toString(retStr);
174 	}
175 
176 	/**
177 	 * Unescapes a segment of an escaped string.
178 	 *
179 	 * If any of the characters in @illegal_characters or the character zero appears
180 	 * as an escaped character in @escaped_string then that is an error and %NULL
181 	 * will be returned. This is useful it you want to avoid for instance having a
182 	 * slash being expanded in an escaped path element, which might confuse pathname
183 	 * handling.
184 	 *
185 	 * Params:
186 	 *     escapedString = A string, may be %NULL
187 	 *     escapedStringEnd = Pointer to end of @escaped_string, may be %NULL
188 	 *     illegalCharacters = An optional string of illegal characters not to be allowed, may be %NULL
189 	 *
190 	 * Return: an unescaped version of @escaped_string or %NULL on error.
191 	 *     The returned string should be freed when no longer needed.  As a
192 	 *     special case if %NULL is given for @escaped_string, this function
193 	 *     will return %NULL.
194 	 *
195 	 * Since: 2.16
196 	 */
197 	public static string uriUnescapeSegment(string escapedString, string escapedStringEnd, string illegalCharacters)
198 	{
199 		auto retStr = g_uri_unescape_segment(Str.toStringz(escapedString), Str.toStringz(escapedStringEnd), Str.toStringz(illegalCharacters));
200 		
201 		scope(exit) Str.freeString(retStr);
202 		return Str.toString(retStr);
203 	}
204 
205 	/**
206 	 * Unescapes a whole escaped string.
207 	 *
208 	 * If any of the characters in @illegal_characters or the character zero appears
209 	 * as an escaped character in @escaped_string then that is an error and %NULL
210 	 * will be returned. This is useful it you want to avoid for instance having a
211 	 * slash being expanded in an escaped path element, which might confuse pathname
212 	 * handling.
213 	 *
214 	 * Params:
215 	 *     escapedString = an escaped string to be unescaped.
216 	 *     illegalCharacters = a string of illegal characters not to be
217 	 *         allowed, or %NULL.
218 	 *
219 	 * Return: an unescaped version of @escaped_string. The returned string
220 	 *     should be freed when no longer needed.
221 	 *
222 	 * Since: 2.16
223 	 */
224 	public static string uriUnescapeString(string escapedString, string illegalCharacters)
225 	{
226 		auto retStr = g_uri_unescape_string(Str.toStringz(escapedString), Str.toStringz(illegalCharacters));
227 		
228 		scope(exit) Str.freeString(retStr);
229 		return Str.toString(retStr);
230 	}
231 }