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