libs/binder/include/binder/IBinder.h

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