Home | History | Annotate | Download | only in hwbinder 
      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_HARDWARE_IBINDER_H
     18 #define ANDROID_HARDWARE_IBINDER_H
     19 
     20 #include <functional>
     21 
     22 #include <utils/Errors.h>
     23 #include <utils/RefBase.h>
     24 #include <utils/String16.h>
     25 
     26 // ---------------------------------------------------------------------------
     27 namespace android {
     28 namespace hardware {
     29 
     30 class BHwBinder;
     31 class BpHwBinder;
     32 class IInterface;
     33 class Parcel;
     34 
     35 /**
     36  * Base class and low-level protocol for a remotable object.
     37  * You can derive from this class to create an object for which other
     38  * processes can hold references to it.  Communication between processes
     39  * (method calls, property get and set) is down through a low-level
     40  * protocol implemented on top of the transact() API.
     41  */
     42 class IBinder : public virtual RefBase
     43 {
     44 public:
     45     using TransactCallback = std::function<void(Parcel&)>;
     46 
     47     enum {
     48         // Corresponds to TF_ONE_WAY -- an asynchronous call.
     49         FLAG_ONEWAY             = 0x00000001
     50     };
     51 
     52                           IBinder();
     53 
     54     virtual status_t        transact(   uint32_t code,
     55                                         const Parcel& data,
     56                                         Parcel* reply,
     57                                         uint32_t flags = 0,
     58                                         TransactCallback callback = nullptr) = 0;
     59 
     60     class DeathRecipient : public virtual RefBase
     61     {
     62     public:
     63         virtual void binderDied(const wp<IBinder>& who) = 0;
     64     };
     65 
     66     /**
     67      * Register the @a recipient for a notification if this binder
     68      * goes away.  If this binder object unexpectedly goes away
     69      * (typically because its hosting process has been killed),
     70      * then DeathRecipient::binderDied() will be called with a reference
     71      * to this.
     72      *
     73      * The @a cookie is optional -- if non-NULL, it should be a
     74      * memory address that you own (that is, you know it is unique).
     75      *
     76      * @note You will only receive death notifications for remote binders,
     77      * as local binders by definition can't die without you dying as well.
     78      * Trying to use this function on a local binder will result in an
     79      * INVALID_OPERATION code being returned and nothing happening.
     80      *
     81      * @note This link always holds a weak reference to its recipient.
     82      *
     83      * @note You will only receive a weak reference to the dead
     84      * binder.  You should not try to promote this to a strong reference.
     85      * (Nor should you need to, as there is nothing useful you can
     86      * directly do with it now that it has passed on.)
     87      */
     88     virtual status_t        linkToDeath(const sp<DeathRecipient>& recipient,
     89                                         void* cookie = NULL,
     90                                         uint32_t flags = 0) = 0;
     91 
     92     /**
     93      * Remove a previously registered death notification.
     94      * The @a recipient will no longer be called if this object
     95      * dies.  The @a cookie is optional.  If non-NULL, you can
     96      * supply a NULL @a recipient, and the recipient previously
     97      * added with that cookie will be unlinked.
     98      */
     99     virtual status_t        unlinkToDeath(  const wp<DeathRecipient>& recipient,
    100                                             void* cookie = NULL,
    101                                             uint32_t flags = 0,
    102                                             wp<DeathRecipient>* outRecipient = NULL) = 0;
    103 
    104     virtual bool            checkSubclass(const void* subclassID) const;
    105 
    106     typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
    107 
    108     virtual void            attachObject(   const void* objectID,
    109                                             void* object,
    110                                             void* cleanupCookie,
    111                                             object_cleanup_func func) = 0;
    112     virtual void*           findObject(const void* objectID) const = 0;
    113     virtual void            detachObject(const void* objectID) = 0;
    114 
    115     virtual BHwBinder*        localBinder();
    116     virtual BpHwBinder*       remoteBinder();
    117 
    118 protected:
    119     virtual          ~IBinder();
    120 
    121 private:
    122 };
    123 
    124 }; // namespace hardware
    125 }; // namespace android
    126 
    127 // ---------------------------------------------------------------------------
    128 
    129 #endif // ANDROID_HARDWARE_IBINDER_H
    130