offapi/com/sun/star/util/XOfficeInstallationDirectories.idl

   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 module com { module sun { module star { module util {
  21
  22 /** encapsulates access to the current office installation directory and
  23     office user data directory, provides functionality to create URLs
  24     containing relocatable (not absolute) references to the current office
  25     installation directory and user data directory and vice versa.
  26
  27     <p>This functionality is useful when data containing references to the
  28     current office installation directory must be made persistent and re-read
  29     later. In many cases, storing the reference directly would destroy the
  30     relocatability of an office installation.
  31
  32     @since OOo 2.0
  33  */
  34 published interface XOfficeInstallationDirectories : com::sun::star::uno::XInterface
  35 {
  36     /** returns the absolute URL containing the directory of the current office
  37         installation (for example "file:///opt/LibreOffice")
  38
  39         @returns
  40         the absolute URL containing the directory of the current office
  41         installation.
  42      */
  43     string getOfficeInstallationDirectoryURL();
  44
  45     /** returns the absolute URL containing the directory where the current
  46         office installation expects its user data (for example
  47         "file:///home/kso/.config/libreoffice/4")
  48
  49         @returns
  50         the absolute URL containing the directory of the current office
  51         user data.
  52      */
  53     string getOfficeUserDataDirectoryURL();
  54
  55     /** calculates a relocatable URL from the given URL.
  56
  57         <p>If the given URL contains an absolute reference to the current office
  58         installation directory or office user data directory, this method will
  59         replace the absolute reference by an opaque placeholder string.
  60         <code>makeRelocatableURL</code> must be used in order to re-replace the
  61         placeholder by an absolute reference.
  62
  63         @param URL
  64         The URL for that a relocatable URL is requested. In case the URL does
  65         not contain a reference to the current office installation or to the office
  66         user data directory, the input URL will be returned unchanged.
  67
  68         @returns
  69         The relocatable URL.
  70      */
  71     string makeRelocatableURL( [in] string URL );
  72
  73     /** the counterpart of <code>makeRelocatableURL</code>.
  74
  75         <p>If the given URL contains a placeholder for an absolute reference to
  76         the current office installation directory or for the office user data
  77         directory, that was created using <code>makeRelocatableURL</code>, the
  78         respective placeholder will be replaced by an absolute reference to the
  79         current office installation directory or office user data directory.
  80
  81         @param URL
  82         The URL for that an absolute URL is requested. In case the URL does
  83         not contain the opaque relocation placeholder used by
  84         <code>makeRelocatableURL</code>, the input URL will be returned
  85         unchanged.
  86
  87         @returns
  88         The absolute URL.
  89      */
  90     string makeAbsoluteURL( [in] string URL );
  91 };
  92
  93 }; }; }; };
  94
  95 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */