michael@0: /*
michael@0:  * Copyright (C) 2008 The Android Open Source Project
michael@0:  *
michael@0:  * Licensed under the Apache License, Version 2.0 (the "License");
michael@0:  * you may not use this file except in compliance with the License.
michael@0:  * You may obtain a copy of the License at
michael@0:  *
michael@0:  *      http://www.apache.org/licenses/LICENSE-2.0
michael@0:  *
michael@0:  * Unless required by applicable law or agreed to in writing, software
michael@0:  * distributed under the License is distributed on an "AS IS" BASIS,
michael@0:  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
michael@0:  * See the License for the specific language governing permissions and
michael@0:  * limitations under the License.
michael@0:  */
michael@0: 
michael@0: #ifndef ANDROID_IBINDER_H
michael@0: #define ANDROID_IBINDER_H
michael@0: 
michael@0: #include <utils/Errors.h>
michael@0: #include <utils/RefBase.h>
michael@0: #include <utils/String16.h>
michael@0: #include <utils/Vector.h>
michael@0: 
michael@0: 
michael@0: #define B_PACK_CHARS(c1, c2, c3, c4) \
michael@0:     ((((c1)<<24)) | (((c2)<<16)) | (((c3)<<8)) | (c4))
michael@0: 
michael@0: // ---------------------------------------------------------------------------
michael@0: namespace android {
michael@0: 
michael@0: class BBinder;
michael@0: class BpBinder;
michael@0: class IInterface;
michael@0: class Parcel;
michael@0: 
michael@0: /**
michael@0:  * Base class and low-level protocol for a remotable object.
michael@0:  * You can derive from this class to create an object for which other
michael@0:  * processes can hold references to it.  Communication between processes
michael@0:  * (method calls, property get and set) is down through a low-level
michael@0:  * protocol implemented on top of the transact() API.
michael@0:  */
michael@0: class IBinder : public virtual RefBase
michael@0: {
michael@0: public:
michael@0:     enum {
michael@0:         FIRST_CALL_TRANSACTION  = 0x00000001,
michael@0:         LAST_CALL_TRANSACTION   = 0x00ffffff,
michael@0: 
michael@0:         PING_TRANSACTION        = B_PACK_CHARS('_','P','N','G'),
michael@0:         DUMP_TRANSACTION        = B_PACK_CHARS('_','D','M','P'),
michael@0:         INTERFACE_TRANSACTION   = B_PACK_CHARS('_', 'N', 'T', 'F'),
michael@0: 
michael@0:         // Corresponds to TF_ONE_WAY -- an asynchronous call.
michael@0:         FLAG_ONEWAY             = 0x00000001
michael@0:     };
michael@0: 
michael@0:                           IBinder();
michael@0: 
michael@0:     /**
michael@0:      * Check if this IBinder implements the interface named by
michael@0:      * @a descriptor.  If it does, the base pointer to it is returned,
michael@0:      * which you can safely static_cast<> to the concrete C++ interface.
michael@0:      */
michael@0:     virtual sp<IInterface>  queryLocalInterface(const String16& descriptor);
michael@0: 
michael@0:     /**
michael@0:      * Return the canonical name of the interface provided by this IBinder
michael@0:      * object.
michael@0:      */
michael@0:     virtual const String16& getInterfaceDescriptor() const = 0;
michael@0: 
michael@0:     virtual bool            isBinderAlive() const = 0;
michael@0:     virtual status_t        pingBinder() = 0;
michael@0:     virtual status_t        dump(int fd, const Vector<String16>& args) = 0;
michael@0: 
michael@0:     virtual status_t        transact(   uint32_t code,
michael@0:                                         const Parcel& data,
michael@0:                                         Parcel* reply,
michael@0:                                         uint32_t flags = 0) = 0;
michael@0: 
michael@0:     /**
michael@0:      * This method allows you to add data that is transported through
michael@0:      * IPC along with your IBinder pointer.  When implementing a Binder
michael@0:      * object, override it to write your desired data in to @a outData.
michael@0:      * You can then call getConstantData() on your IBinder to retrieve
michael@0:      * that data, from any process.  You MUST return the number of bytes
michael@0:      * written in to the parcel (including padding).
michael@0:      */
michael@0:     class DeathRecipient : public virtual RefBase
michael@0:     {
michael@0:     public:
michael@0:         virtual void binderDied(const wp<IBinder>& who) = 0;
michael@0:     };
michael@0: 
michael@0:     /**
michael@0:      * Register the @a recipient for a notification if this binder
michael@0:      * goes away.  If this binder object unexpectedly goes away
michael@0:      * (typically because its hosting process has been killed),
michael@0:      * then DeathRecipient::binderDied() will be called with a referene
michael@0:      * to this.
michael@0:      *
michael@0:      * The @a cookie is optional -- if non-NULL, it should be a
michael@0:      * memory address that you own (that is, you know it is unique).
michael@0:      *
michael@0:      * @note You will only receive death notifications for remote binders,
michael@0:      * as local binders by definition can't die without you dying as well.
michael@0:      * Trying to use this function on a local binder will result in an
michael@0:      * INVALID_OPERATION code being returned and nothing happening.
michael@0:      *
michael@0:      * @note This link always holds a weak reference to its recipient.
michael@0:      *
michael@0:      * @note You will only receive a weak reference to the dead
michael@0:      * binder.  You should not try to promote this to a strong reference.
michael@0:      * (Nor should you need to, as there is nothing useful you can
michael@0:      * directly do with it now that it has passed on.)
michael@0:      */
michael@0:     virtual status_t        linkToDeath(const sp<DeathRecipient>& recipient,
michael@0:                                         void* cookie = NULL,
michael@0:                                         uint32_t flags = 0) = 0;
michael@0: 
michael@0:     /**
michael@0:      * Remove a previously registered death notification.
michael@0:      * The @a recipient will no longer be called if this object
michael@0:      * dies.  The @a cookie is optional.  If non-NULL, you can
michael@0:      * supply a NULL @a recipient, and the recipient previously
michael@0:      * added with that cookie will be unlinked.
michael@0:      */
michael@0:     virtual status_t        unlinkToDeath(  const wp<DeathRecipient>& recipient,
michael@0:                                             void* cookie = NULL,
michael@0:                                             uint32_t flags = 0,
michael@0:                                             wp<DeathRecipient>* outRecipient = NULL) = 0;
michael@0: 
michael@0:     virtual bool            checkSubclass(const void* subclassID) const;
michael@0: 
michael@0:     typedef void (*object_cleanup_func)(const void* id, void* obj, void* cleanupCookie);
michael@0: 
michael@0:     virtual void            attachObject(   const void* objectID,
michael@0:                                             void* object,
michael@0:                                             void* cleanupCookie,
michael@0:                                             object_cleanup_func func) = 0;
michael@0:     virtual void*           findObject(const void* objectID) const = 0;
michael@0:     virtual void            detachObject(const void* objectID) = 0;
michael@0: 
michael@0:     virtual BBinder*        localBinder();
michael@0:     virtual BpBinder*       remoteBinder();
michael@0: 
michael@0: protected:
michael@0:     virtual          ~IBinder();
michael@0: 
michael@0: private:
michael@0: };
michael@0: 
michael@0: }; // namespace android
michael@0: 
michael@0: // ---------------------------------------------------------------------------
michael@0: 
michael@0: #endif // ANDROID_IBINDER_H