1 /* 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 // --------------------------------------------------------------------------- 30 namespace android { 31 32 class BBinder; 33 class BpBinder; 34 class IInterface; 35 class Parcel; 36 37 /** 38 * Base class and low-level protocol for a remotable object. 39 * You can derive from this class to create an object for which other 40 * processes can hold references to it. Communication between processes 41 * (method calls, property get and set) is down through a low-level 42 * protocol implemented on top of the transact() API. 43 */ 44 class IBinder : public virtual RefBase 45 { 46 public: 47 enum { 48 FIRST_CALL_TRANSACTION = 0x00000001, 49 LAST_CALL_TRANSACTION = 0x00ffffff, 50 51 PING_TRANSACTION = B_PACK_CHARS('_','P','N','G'), 52 DUMP_TRANSACTION = B_PACK_CHARS('_','D','M','P'), 53 INTERFACE_TRANSACTION = B_PACK_CHARS('_', 'N', 'T', 'F'), 54 SYSPROPS_TRANSACTION = B_PACK_CHARS('_', 'S', 'P', 'R'), 55 56 // Corresponds to TF_ONE_WAY -- an asynchronous call. 57 FLAG_ONEWAY = 0x00000001 58 }; 59 60 IBinder(); 61 62 /** 63 * Check if this IBinder implements the interface named by 64 * @a descriptor. If it does, the base pointer to it is returned, 65 * which you can safely static_cast<> to the concrete C++ interface. 66 */ 67 virtual sp<IInterface> queryLocalInterface(const String16& descriptor); 68 69 /** 70 * Return the canonical name of the interface provided by this IBinder 71 * object. 72 */ 73 virtual const String16& getInterfaceDescriptor() const = 0; 74 75 virtual bool isBinderAlive() const = 0; 76 virtual status_t pingBinder() = 0; 77 virtual status_t dump(int fd, const Vector<String16>& args) = 0; 78 79 virtual status_t transact( uint32_t code, 80 const Parcel& data, 81 Parcel* reply, 82 uint32_t flags = 0) = 0; 83 84 /** 85 * This method allows you to add data that is transported through 86 * IPC along with your IBinder pointer. When implementing a Binder 87 * object, override it to write your desired data in to @a outData. 88 * You can then call getConstantData() on your IBinder to retrieve 89 * that data, from any process. You MUST return the number of bytes 90 * written in to the parcel (including padding). 91 */ 92 class DeathRecipient : public virtual RefBase 93 { 94 public: 95 virtual void binderDied(const wp<IBinder>& who) = 0; 96 }; 97 98 /** 99 * Register the @a recipient for a notification if this binder 100 * goes away. If this binder object unexpectedly goes away 101 * (typically because its hosting process has been killed), 102 * then DeathRecipient::binderDied() will be called with a reference 103 * to this. 104 * 105 * The @a cookie is optional -- if non-NULL, it should be a 106 * memory address that you own (that is, you know it is unique). 107 * 108 * @note You will only receive death notifications for remote binders, 109 * as local binders by definition can't die without you dying as well. 110 * Trying to use this function on a local binder will result in an 111 * INVALID_OPERATION code being returned and nothing happening. 112 * 113 * @note This link always holds a weak reference to its recipient. 114 * 115 * @note You will only receive a weak reference to the dead 116 * binder. You should not try to promote this to a strong reference. 117 * (Nor should you need to, as there is nothing useful you can 118 * directly do with it now that it has passed on.) 119 */ 120 virtual status_t linkToDeath(const sp<DeathRecipient>& recipient, 121 void* cookie = NULL, 122 uint32_t flags = 0) = 0; 123 124 /** 125 * Remove a previously registered death notification. 126 * The @a recipient will no longer be called if this object 127 * dies. The @a cookie is optional. If non-NULL, you can 128 * supply a NULL @a recipient, and the recipient previously 129 * added with that cookie will be unlinked. 130 */ 131 virtual status_t unlinkToDeath( const wp<DeathRecipient>& recipient, 132 void* cookie = NULL, 133 uint32_t flags = 0, 134 wp<DeathRecipient>* outRecipient = NULL) = 0; 135 136 virtual bool checkSubclass(const void* subclassID) const; 137 138 typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie); 139 140 virtual void attachObject( const void* objectID, 141 void* object, 142 void* cleanupCookie, 143 object_cleanup_func func) = 0; 144 virtual void* findObject(const void* objectID) const = 0; 145 virtual void detachObject(const void* objectID) = 0; 146 147 virtual BBinder* localBinder(); 148 virtual BpBinder* remoteBinder(); 149 150 protected: 151 virtual ~IBinder(); 152 153 private: 154 }; 155 156 }; // namespace android 157 158 // --------------------------------------------------------------------------- 159 160 #endif // ANDROID_IBINDER_H 161