84f8692f52a9debea882e704c4a952a0afb8840c
[dbus-ada.git] / src / d_bus-connection.ads
1 --
2 --  D_Bus/Ada - An Ada binding to D-Bus
3 --
4 --  Copyright (C) 2011-2015  Reto Buerki <reet@codelabs.ch>
5 --
6 --  This program is free software; you can redistribute it and/or
7 --  modify it under the terms of the GNU General Public License
8 --  as published by the Free Software Foundation; either version 2
9 --  of the License, or (at your option) any later version.
10 --
11 --  This program is distributed in the hope that it will be useful,
12 --  but WITHOUT ANY WARRANTY; without even the implied warranty of
13 --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 --  GNU General Public License for more details.
15 --
16 --  You should have received a copy of the GNU General Public License
17 --  along with this program; if not, write to the Free Software
18 --  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
19 --  USA.
20 --
21 --  As a special exception, if other files instantiate generics from this
22 --  unit,  or  you  link  this  unit  with  other  files  to  produce  an
23 --  executable   this  unit  does  not  by  itself  cause  the  resulting
24 --  executable to  be  covered by the  GNU General  Public License.  This
25 --  exception does  not  however  invalidate  any  other reasons why  the
26 --  executable file might be covered by the GNU Public License.
27 --
28
29 with dbus_connection_h;
30 private with dbus_pending_call_h;
31
32 with D_Bus.Arguments;
33 with D_Bus.Messages;
34 with D_Bus.Types;
35
36 package D_Bus.Connection is
37
38    type Connection_Type (<>) is limited private;
39    --  D-Bus connection.
40
41    function Connect (Bus : Bus_Type := Bus_Session) return Connection_Type;
42    --  Connect to the given message bus type.
43
44    function Connect (Address : String) return Connection_Type;
45    --  Connect to the given remote address.
46
47    subtype Timeout_Type is Integer range -1 .. Integer'Last;
48
49    Default_Timeout : constant Timeout_Type;
50
51    function Call_Blocking
52      (Connection   : Connection_Type;
53       Destination  : String;
54       Path         : Types.Obj_Path;
55       Iface        : String;
56       Method       : String;
57       Timeout_Msec : Timeout_Type                 := Default_Timeout;
58       Args         : Arguments.Argument_List_Type :=
59         Arguments.Empty_Argument_List)
60       return Arguments.Argument_List_Type;
61    --  Synchronously call the given method.
62
63    procedure Send_Signal
64      (Connection  : Connection_Type;
65       Object_Name : Types.Obj_Path;
66       Iface       : String;
67       Name        : String;
68       Args        : Arguments.Argument_List_Type :=
69         Arguments.Empty_Argument_List);
70    --  Send a signal over the given connection.
71
72    procedure Send
73      (Connection : Connection_Type;
74       Message    : Messages.Message_Type);
75    --  Add given message to the outgoing message queue.
76
77    procedure Request_Name
78      (Connection : Connection_Type;
79       Name       : String);
80    --  Request name on the bus for given connection.
81
82    procedure Add_Match
83      (Connection : Connection_Type;
84       Rule       : String);
85    --  Add given match rule to match messages going through the message bus.
86
87    function Read_Write
88      (Connection   : Connection_Type;
89       Timeout_Msec : Timeout_Type)
90       return Boolean;
91    --  The return value indicates whether reading or writing is still possible
92    --  for the specified connection, i.e. whether the connection is connected.
93
94    procedure Pop_Message
95      (Connection :     Connection_Type;
96       Message    : out Messages.Message_Type);
97    --  Returns the first-received message from the incoming message queue,
98    --  removing it from the queue. The caller owns a reference to the returned
99    --  message. If the queue is empty, Null_Message is returned.
100
101    procedure Flush (Connection : Connection_Type);
102    --  Send any pending messages.
103
104 private
105
106    Default_Timeout : constant Timeout_Type
107      := dbus_pending_call_h.DBUS_TIMEOUT_USE_DEFAULT;
108
109    type Connection_Type is limited record
110       Thin_Connection : access dbus_connection_h.DBusConnection := null;
111    end record;
112
113 end D_Bus.Connection;