blob: 97f1fc2844bdd15ea1ec64c8e08a90cb8fb4c3df [file] [log] [blame]
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -08001/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_IBINDER_H
18#define ANDROID_IBINDER_H
19
20#include <utils/Errors.h>
21#include <utils/RefBase.h>
22#include <utils/String16.h>
23#include <utils/Vector.h>
24
25
26#define B_PACK_CHARS(c1, c2, c3, c4) \
27 ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4))
28
29// ---------------------------------------------------------------------------
30namespace android {
31
32class BBinder;
33class BpBinder;
34class IInterface;
35class Parcel;
Dianne Hackborn23eb1e22015-10-07 17:35:27 -070036class IResultReceiver;
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080037
38/**
39 * Base class and low-level protocol for a remotable object.
40 * You can derive from this class to create an object for which other
41 * processes can hold references to it. Communication between processes
42 * (method calls, property get and set) is down through a low-level
43 * protocol implemented on top of the transact() API.
44 */
45class IBinder : public virtual RefBase
46{
47public:
48 enum {
49 FIRST_CALL_TRANSACTION = 0x00000001,
50 LAST_CALL_TRANSACTION = 0x00ffffff,
51
52 PING_TRANSACTION = B_PACK_CHARS('_','P','N','G'),
53 DUMP_TRANSACTION = B_PACK_CHARS('_','D','M','P'),
Dianne Hackborn23eb1e22015-10-07 17:35:27 -070054 SHELL_COMMAND_TRANSACTION = B_PACK_CHARS('_','C','M','D'),
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080055 INTERFACE_TRANSACTION = B_PACK_CHARS('_', 'N', 'T', 'F'),
Dianne Hackborn555f89d2012-05-08 18:54:22 -070056 SYSPROPS_TRANSACTION = B_PACK_CHARS('_', 'S', 'P', 'R'),
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080057
Dianne Hackborn8c6cedc2009-12-07 17:59:37 -080058 // Corresponds to TF_ONE_WAY -- an asynchronous call.
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080059 FLAG_ONEWAY = 0x00000001
60 };
61
Mathias Agopian83c04462009-05-22 19:00:22 -070062 IBinder();
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080063
64 /**
65 * Check if this IBinder implements the interface named by
66 * @a descriptor. If it does, the base pointer to it is returned,
67 * which you can safely static_cast<> to the concrete C++ interface.
68 */
69 virtual sp<IInterface> queryLocalInterface(const String16& descriptor);
70
71 /**
72 * Return the canonical name of the interface provided by this IBinder
73 * object.
74 */
Mathias Agopian83c04462009-05-22 19:00:22 -070075 virtual const String16& getInterfaceDescriptor() const = 0;
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080076
77 virtual bool isBinderAlive() const = 0;
78 virtual status_t pingBinder() = 0;
79 virtual status_t dump(int fd, const Vector<String16>& args) = 0;
Dianne Hackbornf2bf93b2015-10-14 15:13:02 -070080 static status_t shellCommand(const sp<IBinder>& target, int in, int out, int err,
81 Vector<String16>& args,
Dianne Hackborn23eb1e22015-10-07 17:35:27 -070082 const sp<IResultReceiver>& resultReceiver);
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080083
84 virtual status_t transact( uint32_t code,
85 const Parcel& data,
86 Parcel* reply,
87 uint32_t flags = 0) = 0;
88
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -080089 class DeathRecipient : public virtual RefBase
90 {
91 public:
92 virtual void binderDied(const wp<IBinder>& who) = 0;
93 };
94
95 /**
96 * Register the @a recipient for a notification if this binder
97 * goes away. If this binder object unexpectedly goes away
98 * (typically because its hosting process has been killed),
Christopher Tate71f64dd2011-02-17 13:00:38 -080099 * then DeathRecipient::binderDied() will be called with a reference
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -0800100 * to this.
101 *
102 * The @a cookie is optional -- if non-NULL, it should be a
103 * memory address that you own (that is, you know it is unique).
104 *
105 * @note You will only receive death notifications for remote binders,
106 * as local binders by definition can't die without you dying as well.
107 * Trying to use this function on a local binder will result in an
108 * INVALID_OPERATION code being returned and nothing happening.
109 *
110 * @note This link always holds a weak reference to its recipient.
111 *
112 * @note You will only receive a weak reference to the dead
113 * binder. You should not try to promote this to a strong reference.
114 * (Nor should you need to, as there is nothing useful you can
115 * directly do with it now that it has passed on.)
116 */
117 virtual status_t linkToDeath(const sp<DeathRecipient>& recipient,
118 void* cookie = NULL,
119 uint32_t flags = 0) = 0;
120
121 /**
122 * Remove a previously registered death notification.
123 * The @a recipient will no longer be called if this object
124 * dies. The @a cookie is optional. If non-NULL, you can
125 * supply a NULL @a recipient, and the recipient previously
126 * added with that cookie will be unlinked.
127 */
128 virtual status_t unlinkToDeath( const wp<DeathRecipient>& recipient,
129 void* cookie = NULL,
130 uint32_t flags = 0,
131 wp<DeathRecipient>* outRecipient = NULL) = 0;
132
133 virtual bool checkSubclass(const void* subclassID) const;
134
135 typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
136
137 virtual void attachObject( const void* objectID,
138 void* object,
139 void* cleanupCookie,
140 object_cleanup_func func) = 0;
141 virtual void* findObject(const void* objectID) const = 0;
142 virtual void detachObject(const void* objectID) = 0;
143
144 virtual BBinder* localBinder();
145 virtual BpBinder* remoteBinder();
146
147protected:
Mathias Agopian83c04462009-05-22 19:00:22 -0700148 virtual ~IBinder();
The Android Open Source Projectedbf3b62009-03-03 19:31:44 -0800149
150private:
151};
152
153}; // namespace android
154
155// ---------------------------------------------------------------------------
156
157#endif // ANDROID_IBINDER_H