| 1 | /*
|
|---|
| 2 | Unix SMB/CIFS implementation.
|
|---|
| 3 | Infrastructure for async requests
|
|---|
| 4 | Copyright (C) Volker Lendecke 2008
|
|---|
| 5 |
|
|---|
| 6 | This program is free software; you can redistribute it and/or modify
|
|---|
| 7 | it under the terms of the GNU General Public License as published by
|
|---|
| 8 | the Free Software Foundation; either version 3 of the License, or
|
|---|
| 9 | (at your option) any later version.
|
|---|
| 10 |
|
|---|
| 11 | This program is distributed in the hope that it will be useful,
|
|---|
| 12 | but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|---|
| 13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|---|
| 14 | GNU General Public License for more details.
|
|---|
| 15 |
|
|---|
| 16 | You should have received a copy of the GNU General Public License
|
|---|
| 17 | along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|---|
| 18 | */
|
|---|
| 19 |
|
|---|
| 20 | #ifndef __ASYNC_REQ_H__
|
|---|
| 21 | #define __ASYNC_REQ_H__
|
|---|
| 22 |
|
|---|
| 23 | #include "includes.h"
|
|---|
| 24 |
|
|---|
| 25 | /**
|
|---|
| 26 | * An async request moves between the following 4 states:
|
|---|
| 27 | */
|
|---|
| 28 |
|
|---|
| 29 | enum async_req_state {
|
|---|
| 30 | /**
|
|---|
| 31 | * we are creating the request
|
|---|
| 32 | */
|
|---|
| 33 | ASYNC_REQ_INIT,
|
|---|
| 34 | /**
|
|---|
| 35 | * we are waiting the request to complete
|
|---|
| 36 | */
|
|---|
| 37 | ASYNC_REQ_IN_PROGRESS,
|
|---|
| 38 | /**
|
|---|
| 39 | * the request is finished
|
|---|
| 40 | */
|
|---|
| 41 | ASYNC_REQ_DONE,
|
|---|
| 42 | /**
|
|---|
| 43 | * an error has occured
|
|---|
| 44 | */
|
|---|
| 45 | ASYNC_REQ_ERROR
|
|---|
| 46 | };
|
|---|
| 47 |
|
|---|
| 48 | /**
|
|---|
| 49 | * @brief An async request
|
|---|
| 50 | *
|
|---|
| 51 | * This represents an async request being processed by callbacks via an event
|
|---|
| 52 | * context. A user can issue for example a write request to a socket, giving
|
|---|
| 53 | * an implementation function the fd, the buffer and the number of bytes to
|
|---|
| 54 | * transfer. The function issuing the request will immediately return without
|
|---|
| 55 | * blocking most likely without having sent anything. The API user then fills
|
|---|
| 56 | * in req->async.fn and req->async.priv, functions that are called when the
|
|---|
| 57 | * request is finished.
|
|---|
| 58 | *
|
|---|
| 59 | * It is up to the user of the async request to talloc_free it after it has
|
|---|
| 60 | * finished. This can happen while the completion function is called.
|
|---|
| 61 | */
|
|---|
| 62 |
|
|---|
| 63 | struct async_req {
|
|---|
| 64 | /**
|
|---|
| 65 | * @brief The external state - will be queried by the caller
|
|---|
| 66 | *
|
|---|
| 67 | * While the async request is being processed, state will remain in
|
|---|
| 68 | * ASYNC_REQ_IN_PROGRESS. A request is finished if
|
|---|
| 69 | * req->state>=ASYNC_REQ_DONE.
|
|---|
| 70 | */
|
|---|
| 71 | enum async_req_state state;
|
|---|
| 72 |
|
|---|
| 73 | /**
|
|---|
| 74 | * @brief Private pointer for the actual implementation
|
|---|
| 75 | *
|
|---|
| 76 | * The implementation doing the work for the async request needs a
|
|---|
| 77 | * current state like for example a fd event. The user of an async
|
|---|
| 78 | * request should not touch this.
|
|---|
| 79 | */
|
|---|
| 80 | void *private_data;
|
|---|
| 81 |
|
|---|
| 82 | /**
|
|---|
| 83 | * @brief Print yourself, for debugging purposes
|
|---|
| 84 | *
|
|---|
| 85 | * Async requests are opaque data structures. The implementation of an
|
|---|
| 86 | * async request can define a custom function to print more debug
|
|---|
| 87 | * info.
|
|---|
| 88 | */
|
|---|
| 89 | char *(*print)(TALLOC_CTX *mem_ctx, struct async_req *);
|
|---|
| 90 |
|
|---|
| 91 | /**
|
|---|
| 92 | * @brief status code when finished
|
|---|
| 93 | *
|
|---|
| 94 | * This status can be queried in the async completion function. It
|
|---|
| 95 | * will be set to NT_STATUS_OK when everything went fine.
|
|---|
| 96 | **/
|
|---|
| 97 | NTSTATUS status;
|
|---|
| 98 |
|
|---|
| 99 | /**
|
|---|
| 100 | * @brief The event context we are using
|
|---|
| 101 | *
|
|---|
| 102 | * The event context that this async request works on.
|
|---|
| 103 | */
|
|---|
| 104 | struct event_context *event_ctx;
|
|---|
| 105 |
|
|---|
| 106 | /**
|
|---|
| 107 | * @brief What to do on completion
|
|---|
| 108 | *
|
|---|
| 109 | * This is used for the user of an async request, fn is called when
|
|---|
| 110 | * the request completes, either successfully or with an error.
|
|---|
| 111 | */
|
|---|
| 112 | struct {
|
|---|
| 113 | /**
|
|---|
| 114 | * @brief Completion function
|
|---|
| 115 | * Completion function, to be filled by the API user
|
|---|
| 116 | */
|
|---|
| 117 | void (*fn)(struct async_req *);
|
|---|
| 118 | /**
|
|---|
| 119 | * @brief Private data for the completion function
|
|---|
| 120 | */
|
|---|
| 121 | void *priv;
|
|---|
| 122 | } async;
|
|---|
| 123 | };
|
|---|
| 124 |
|
|---|
| 125 | struct async_req *async_req_new(TALLOC_CTX *mem_ctx, struct event_context *ev);
|
|---|
| 126 |
|
|---|
| 127 | char *async_req_print(TALLOC_CTX *mem_ctx, struct async_req *req);
|
|---|
| 128 |
|
|---|
| 129 | void async_req_done(struct async_req *req);
|
|---|
| 130 |
|
|---|
| 131 | void async_req_error(struct async_req *req, NTSTATUS status);
|
|---|
| 132 |
|
|---|
| 133 | bool async_post_status(struct async_req *req, NTSTATUS status);
|
|---|
| 134 |
|
|---|
| 135 | bool async_req_nomem(const void *p, struct async_req *req);
|
|---|
| 136 |
|
|---|
| 137 | #endif
|
|---|
