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