| /************************************************************** |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| |
| #ifndef __com_sun_star_uri_XUriReferenceFactory_idl__ |
| #define __com_sun_star_uri_XUriReferenceFactory_idl__ |
| |
| #include <com/sun/star/uno/XInterface.idl> |
| #include <com/sun/star/uri/RelativeUriExcessParentSegments.idl> |
| #include <com/sun/star/uri/XUriReference.idl> |
| |
| module com { module sun { module star { module uri { |
| |
| /** |
| creates URI references. |
| |
| <p>See <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a> for a |
| description of URI references and related terms.</p> |
| |
| @since OpenOffice 2.0 |
| */ |
| published interface XUriReferenceFactory: com::sun::star::uno::XInterface { |
| /** |
| parses the textual representation of a URI reference. |
| |
| @param uriReference |
| the textual representation of a URI reference. |
| |
| @returns |
| an object that supports |
| <type scope="com::sun::star::uri">XUriReference</type> (and possibly also |
| additional, scheme-specific interfaces), if the given input can be parsed |
| into a URI reference; otherwise, <NULL/> is returned. |
| */ |
| XUriReference parse([in] string uriReference); |
| |
| /** |
| resolves a relative URI reference to absolute form. |
| |
| @param baseUriReference |
| the base URI reference. If the given <code>uriReference</code> is a |
| same-document reference, <code>baseUriReference</code> is used as a |
| reference to the current document. |
| |
| @param uriReference |
| any URI reference. Backwards-compatible relative URI references starting |
| with a scheme component (see RFC 2396, Section 5.2, |
| step 3) are not supported; instead, they are interpreted as absolute |
| URI references. |
| |
| @param processSpecialBaseSegments |
| if <TRUE/>, special segments (“<code>.</code>” and |
| “<code>..</code>”) within the path of the base URI (except |
| for the last, cut-off segment) are processed as suggested by |
| RFC 2396. If <FALSE/>, special segments within the path of the base |
| URI are treated like ordinary segments. |
| |
| @param excessParentSegments |
| details how excess special parent segments |
| (“<code>..</code>”) are handled. |
| |
| @returns |
| a fresh object that supports |
| <type scope="com::sun::star::uri">XUriReference</type> (and possibly also |
| additional, scheme-specific interfaces), if the given |
| <code>uriReference</code> is either already absolute, or can be resolved |
| to an absolute URI reference, relative to the given |
| <code>baseUriReference</code>; otherwise, <NULL/> is returned. |
| Especially, if <code>baseUriReference</code> is <NULL/>, or is not an |
| absolute, hierarchical URI reference, or if <code>uriReference</code> is |
| <NULL/>, then <NULL/> is always returned. |
| */ |
| XUriReference makeAbsolute( |
| [in] XUriReference baseUriReference, [in] XUriReference uriReference, |
| [in] boolean processSpecialBaseSegments, |
| [in] RelativeUriExcessParentSegments excessParentSegments); |
| |
| /** |
| changes an absolute URI refrence to relative form. |
| |
| @param baseUriReference |
| the base URI reference. |
| |
| @param uriReference |
| any URI reference. |
| |
| @param preferAuthorityOverRelativePath |
| controls how a relative URI reference is generated when both |
| <code>baseUriReference</code> (e.g., |
| “<code>scheme://auth/a/b</code>”) and |
| <code>uriReference</code> (e.g., |
| “<code>scheme://auth//c/d</code>”) have the same scheme and |
| authority components, and the path component of <code>uriReference</code> |
| starts with “<code>//</code>”. If <TRUE/>, the generated |
| relative URI reference includes an authority component (e.g., |
| “<code>//auth//c/d</code>”); if <FALSE/>, the generated |
| relative URI reference has a relative path (e.g., |
| “<code>..//c/d</code>”). |
| |
| @param preferAbsoluteOverRelativePath |
| controls how a relative URI reference is generated when both |
| <code>baseUriReference</code> (e.g., |
| “<code>scheme://auth/a/b</code>”) and |
| <code>uriReference</code> (e.g., |
| “<code>scheme://auth/c/d</code>”) have the same scheme and |
| authority components (if present), but share no common path segments. If |
| <TRUE/>, the generated relative URI reference has an absolute path (e.g., |
| “<code>/c/d</code>”); if <FALSE/>, the generated relative URI |
| reference has a relative path (e.g., “<code>../c/d</code>”). |
| |
| @param encodeRetainedSpecialSegments |
| if <TRUE/>, special segments (“<code>.</code>” and |
| “<code>..</code>”) that are already present in the path |
| component of the given <code>uriReference</code> and which end up in a |
| relative path returned from this method, are encoded (as |
| “<code>%2E</code>” and “<code>%2E%2E</code>”, |
| respectively). |
| |
| @returns |
| a fresh object that supports |
| <type scope="com::sun::star::uri">XUriReference</type>, if the given |
| <code>uriReference</code> is either already relative, or is not |
| hierarchical, or is of a different scheme than the given |
| <code>baseUriReference</code>, or can be changed to a relative URI |
| reference, relative to the given <code>baseUriReference</code>; |
| otherwise, <NULL/> is returned. Especially, if |
| <code>baseUriReference</code> is <NULL/>, or is not an absolute, |
| hierarchical URI reference, or if <code>uriReference</code> is <NULL/>, |
| then <NULL/> is always returned. |
| */ |
| XUriReference makeRelative( |
| [in] XUriReference baseUriReference, [in] XUriReference uriReference, |
| [in] boolean preferAuthorityOverRelativePath, |
| [in] boolean preferAbsoluteOverRelativePath, |
| [in] boolean encodeRetainedSpecialSegments); |
| }; |
| |
| }; }; }; }; |
| |
| #endif |
