udkapi/com/sun/star/bridge/XProtocolProperties.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 #ifndef _COM_SUN_STAR_BRIDGE_XPROTOCOLPROPERTIES_IDL_
  20 #define _COM_SUN_STAR_BRIDGE_XPROTOCOLPROPERTIES_IDL_
  21 #include <com/sun/star/bridge/ProtocolProperty.idl>
  22 #include <com/sun/star/bridge/InvalidProtocolChangeException.idl>
  23
  24 module com { module sun { module star { module bridge {
  25
  26
  27 /** Bridge internal interface, that allows to change protocol settings of the remote
  28     counter part.
  29
  30     <p>In general, this interface is implemented by the bridge itself. It must not
  31     be called from outside the bridge.</p>
  32
  33     <p>INTERNAL INTERFACE, DO NOT USE IT ELSEWHERE!</p>
  34 */
  35 published interface XProtocolProperties : com::sun::star::uno::XInterface
  36 {
  37     /** called to get a list of bridge internal properties. Which properties can be retrieved,
  38         is protocol dependent.
  39
  40         <p> The properties MUST NOT change between a requestChange and a commit change call.</p>
  41      */
  42     sequence< ProtocolProperty > getProperties( );
  43
  44     /** called to initiate a protocol change.
  45
  46         <p>This method should always be called in the scope of the local bridge setting object,
  47         because the remote counter part may do such a call at the same time
  48         (typically at startup time). </p>
  49
  50         @param nRandomNumber
  51             In case both processes call requestChange at the same time,
  52              the caller with the higher nRandomNumber is allowed to call
  53              commitChange.
  54
  55         @returns
  56             1, if the caller may ( and MUST !!!) call commitChange.
  57             0, if the caller is not allowed to call commitChange. This can only happen,
  58                if the other bridge has called requestChange at the same time and
  59                nRandomNumber is smaller than the other bridge's nRandomNumber.
  60                The remote counterpart is supposed to call commitChange within a small
  61                time span. Please call requestChange() after the remote counterpart has
  62                called commitChange().
  63             -1 if the nRandomNumber is of the same value as the previously
  64                sent requestChange (sent by the remote counterpart). This is a draw :o).
  65                Generate a new random number and try again.
  66      */
  67     long requestChange( [in] long nRandomNumber );
  68
  69     /** called to commit a protocol change.
  70
  71         <p>It is only allowed to call commitChange, if requestChange
  72         has been called previously and the return value was true.  The new properties are
  73         valid after the reply of commitChange has been received.
  74         Note, that this is difficult for the callee, because it must marshal the reply
  75         with the old settings. </p>
  76
  77         <p>All properties not mentioned in the list are unchanged.
  78         Note that the bridge must be blocked for other threads,
  79         before commitChange is sent and unblocked
  80         after the reply has been received. This blocks the bridge.</p>
  81
  82         @throws InvalidProtocolChangeException
  83                 when the remote counterpart could not change at least one of the properties.
  84                 No property has been changed. requestChange must be called
  85                 again to initiate a new change of the protocol.
  86      */
  87     void commitChange( [in] sequence< ProtocolProperty > newValues )
  88         raises ( com::sun::star::bridge::InvalidProtocolChangeException );
  89 };
  90
  91 };};};};
  92 #endif
  93
  94 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */