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