1e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/* 2e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Copyright (C) 2010 The Android Open Source Project 3e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 4e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Licensed under the Apache License, Version 2.0 (the "License"); 5e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * you may not use this file except in compliance with the License. 6e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * You may obtain a copy of the License at 7e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 8e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * http://www.apache.org/licenses/LICENSE-2.0 9e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 10e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Unless required by applicable law or agreed to in writing, software 11e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * distributed under the License is distributed on an "AS IS" BASIS, 12e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * See the License for the specific language governing permissions and 14e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * limitations under the License. 15e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 16e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 17bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine/** 18bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * @addtogroup Looper 19bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * @{ 20bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine */ 21bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine 22bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine/** 23bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * @file looper.h 24bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine */ 25e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 26e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian#ifndef ANDROID_LOOPER_H 27e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian#define ANDROID_LOOPER_H 28e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 29e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian#ifdef __cplusplus 30e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianextern "C" { 31e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian#endif 32e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 33bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosinestruct ALooper; 34e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 35e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * ALooper 36e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 37e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * A looper is the state tracking an event loop for a thread. 38e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Loopers do not define event structures or other such things; rather 39e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * they are a lower-level facility to attach one or more discrete objects 40e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * listening for an event. An "event" here is simply data available on 41e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * a file descriptor: each attached object has an associated file descriptor, 42e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * and waiting for "events" means (internally) polling on all of these file 43e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * descriptors until one or more of them have data available. 44e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 45e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * A thread can have only one ALooper associated with it. 46e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 47e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopiantypedef struct ALooper ALooper; 48e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 49e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 50e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns the looper associated with the calling thread, or NULL if 51e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * there is not one. 52e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 53e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias AgopianALooper* ALooper_forThread(); 54e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 55bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine/** Option for for ALooper_prepare(). */ 56e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianenum { 57e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 58bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * This looper will accept calls to ALooper_addFd() that do not 59bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * have a callback (that is provide NULL for the callback). In 60bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * this case the caller of ALooper_pollOnce() or ALooper_pollAll() 61bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * MUST check the return from these functions to discover when 62bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * data is available on such fds and process it. 63e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 64e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_PREPARE_ALLOW_NON_CALLBACKS = 1<<0 65e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian}; 66e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 67e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 68e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Prepares a looper associated with the calling thread, and returns it. 69e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * If the thread already has a looper, it is returned. Otherwise, a new 70e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * one is created, associated with the thread, and returned. 71e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 72e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The opts may be ALOOPER_PREPARE_ALLOW_NON_CALLBACKS or 0. 73e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 74e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias AgopianALooper* ALooper_prepare(int opts); 75e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 76bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine/** Result from ALooper_pollOnce() and ALooper_pollAll(). */ 77e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianenum { 78e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 79e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The poll was awoken using wake() before the timeout expired 80e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * and no callbacks were executed and no other file descriptors were ready. 81e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 82e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_POLL_WAKE = -1, 83e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 84e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 85e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Result from ALooper_pollOnce() and ALooper_pollAll(): 86e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * One or more callbacks were executed. 87e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 88e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_POLL_CALLBACK = -2, 89e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 90e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 91e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Result from ALooper_pollOnce() and ALooper_pollAll(): 92e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The timeout expired. 93e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 94e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_POLL_TIMEOUT = -3, 95e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 96e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 97e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Result from ALooper_pollOnce() and ALooper_pollAll(): 98e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * An error occurred. 99e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 100e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_POLL_ERROR = -4, 101e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian}; 102e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 103e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 104e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Acquire a reference on the given ALooper object. This prevents the object 105e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * from being deleted until the reference is removed. This is only needed 106e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * to safely hand an ALooper from one thread to another. 107e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 108e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianvoid ALooper_acquire(ALooper* looper); 109e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 110e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 111e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Remove a reference that was previously acquired with ALooper_acquire(). 112e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 113e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianvoid ALooper_release(ALooper* looper); 114e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 115e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 116e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Flags for file descriptor events that a looper can monitor. 117e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 118e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * These flag bits can be combined to monitor multiple events at once. 119e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 120e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianenum { 121e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 122e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The file descriptor is available for read operations. 123e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 124e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_EVENT_INPUT = 1 << 0, 125e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 126e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 127e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The file descriptor is available for write operations. 128e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 129e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_EVENT_OUTPUT = 1 << 1, 130e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 131e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 132e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The file descriptor has encountered an error condition. 133e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 134e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The looper always sends notifications about errors; it is not necessary 135e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * to specify this event flag in the requested event set. 136e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 137e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_EVENT_ERROR = 1 << 2, 138e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 139e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 140e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The file descriptor was hung up. 141e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * For example, indicates that the remote end of a pipe or socket was closed. 142e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 143e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The looper always sends notifications about hangups; it is not necessary 144e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * to specify this event flag in the requested event set. 145e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 146e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_EVENT_HANGUP = 1 << 3, 147e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 148e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian /** 149e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The file descriptor is invalid. 150e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * For example, the file descriptor was closed prematurely. 151e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 152e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The looper always sends notifications about invalid file descriptors; it is not necessary 153e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * to specify this event flag in the requested event set. 154e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 155e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALOOPER_EVENT_INVALID = 1 << 4, 156e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian}; 157e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 158e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 159e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * For callback-based event loops, this is the prototype of the function 160e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * that is called when a file descriptor event occurs. 161e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * It is given the file descriptor it is associated with, 162e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * a bitmask of the poll events that were triggered (typically ALOOPER_EVENT_INPUT), 163e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * and the data pointer that was originally supplied. 164e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 165e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Implementations should return 1 to continue receiving callbacks, or 0 166e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * to have this file descriptor and callback unregistered from the looper. 167e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 168e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopiantypedef int (*ALooper_callbackFunc)(int fd, int events, void* data); 169e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 170e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 171e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Waits for events to be available, with optional timeout in milliseconds. 172e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Invokes callbacks for all file descriptors on which an event occurred. 173e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 174e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * If the timeout is zero, returns immediately without blocking. 175e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * If the timeout is negative, waits indefinitely until an event appears. 176e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 177e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns ALOOPER_POLL_WAKE if the poll was awoken using wake() before 178e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * the timeout expired and no callbacks were invoked and no other file 179e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * descriptors were ready. 180e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 181e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns ALOOPER_POLL_CALLBACK if one or more callbacks were invoked. 182e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 183e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns ALOOPER_POLL_TIMEOUT if there was no data before the given 184e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * timeout expired. 185e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 186e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns ALOOPER_POLL_ERROR if an error occurred. 187e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 188bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * Returns a value >= 0 containing an identifier (the same identifier 189bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * `ident` passed to ALooper_addFd()) if its file descriptor has data 190bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * and it has no callback function (requiring the caller here to 191bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * handle it). In this (and only this) case outFd, outEvents and 192bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * outData will contain the poll events and data associated with the 193bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine * fd, otherwise they will be set to NULL. 194e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 195e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method does not return until it has finished invoking the appropriate callbacks 196e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * for all file descriptors that were signalled. 197e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 198e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianint ALooper_pollOnce(int timeoutMillis, int* outFd, int* outEvents, void** outData); 199e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 200e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 201e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Like ALooper_pollOnce(), but performs all pending callbacks until all 202e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * data has been consumed or a file descriptor is available with no callback. 203e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This function will never return ALOOPER_POLL_CALLBACK. 204e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 205e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianint ALooper_pollAll(int timeoutMillis, int* outFd, int* outEvents, void** outData); 206e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 207e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 208e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Wakes the poll asynchronously. 209e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 210e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method can be called on any thread. 211e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method returns immediately. 212e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 213e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianvoid ALooper_wake(ALooper* looper); 214e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 215e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 216e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Adds a new file descriptor to be polled by the looper. 217e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * If the same file descriptor was previously added, it is replaced. 218e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 219e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * "fd" is the file descriptor to be added. 220e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * "ident" is an identifier for this event, which is returned from ALooper_pollOnce(). 221e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * The identifier must be >= 0, or ALOOPER_POLL_CALLBACK if providing a non-NULL callback. 222e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * "events" are the poll events to wake up on. Typically this is ALOOPER_EVENT_INPUT. 223e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * "callback" is the function to call when there is an event on the file descriptor. 224e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * "data" is a private data pointer to supply to the callback. 225e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 226e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * There are two main uses of this function: 227e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 228e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * (1) If "callback" is non-NULL, then this function will be called when there is 229e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * data on the file descriptor. It should execute any events it has pending, 230e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * appropriately reading from the file descriptor. The 'ident' is ignored in this case. 231e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 232e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * (2) If "callback" is NULL, the 'ident' will be returned by ALooper_pollOnce 233e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * when its file descriptor has data available, requiring the caller to take 234e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * care of processing it. 235e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 236e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns 1 if the file descriptor was added or -1 if an error occurred. 237e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 238e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method can be called on any thread. 239e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method may block briefly if it needs to wake the poll. 240e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 241e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianint ALooper_addFd(ALooper* looper, int fd, int ident, int events, 242e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian ALooper_callbackFunc callback, void* data); 243e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 244e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian/** 245e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Removes a previously added file descriptor from the looper. 246e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 247e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * When this method returns, it is safe to close the file descriptor since the looper 248e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * will no longer have a reference to it. However, it is possible for the callback to 249e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * already be running or for it to run one last time if the file descriptor was already 250e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * signalled. Calling code is responsible for ensuring that this case is safely handled. 251e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * For example, if the callback takes care of removing itself during its own execution either 252e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * by returning 0 or by calling this method, then it can be guaranteed to not be invoked 253e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * again at any later time unless registered anew. 254e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 255e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * Returns 1 if the file descriptor was removed, 0 if none was previously registered 256e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * or -1 if an error occurred. 257e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * 258e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method can be called on any thread. 259e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian * This method may block briefly if it needs to wake the poll. 260e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian */ 261e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopianint ALooper_removeFd(ALooper* looper, int fd); 262e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 263e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian#ifdef __cplusplus 264e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian}; 265e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian#endif 266e1c61d3cc8458ce9a15d8109f728e60f5248939dMathias Agopian 267fe761ab6c72bdcdb8a2cf0df1524f526d8609feeBrian Carlstrom#endif // ANDROID_LOOPER_H 268bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine 269bf6d5e012cd9b15568c2351831f3349cf564bf18Johan Euphrosine/** @} */ 270