1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
/* Copyright 2016 The Chromium OS Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
#ifndef CRAS_FILE_WAIT_H_
#define CRAS_FILE_WAIT_H_
#ifdef __cplusplus
extern "C" {
#endif
/* Structure used to track the current progress of a file wait. */
struct cras_file_wait;
/* Flags type for file wait. */
typedef unsigned int cras_file_wait_flag_t;
/* No flags. */
#define CRAS_FILE_WAIT_FLAG_NONE ((cras_file_wait_flag_t)0)
/* File wait events. */
typedef enum cras_file_wait_event {
CRAS_FILE_WAIT_EVENT_NONE,
CRAS_FILE_WAIT_EVENT_CREATED,
CRAS_FILE_WAIT_EVENT_DELETED,
} cras_file_wait_event_t;
/*
* File wait callback function.
*
* Called for cras_file_wait events. Do not call cras_file_wait_destroy()
* from this function.
*
* Args:
* context - Context pointer passed to cras_file_wait_start().
* event - Event that has occurred related to this file wait.
* filename - Filename associated with the event.
*/
typedef void (*cras_file_wait_callback_t)(void *context,
cras_file_wait_event_t event,
const char *filename);
/*
* Wait for the existence of a file.
*
* Setup a watch with the aim of determining if the given file path exists. If
* any parent directory is missing, then the appropriate watch is created to
* watch for the parent (or it's parent). Watches are created or renewed while
* this file wait structure exists.
*
* The callback function will be called with event CRAS_FILE_WAIT_EVENT_CREATED
* when the file is created, moved into the directory, or if it already exists
* when this function is called.
*
* After the file is found future deletion and creation events for the file can
* be observed using the same file_wait structure and callback. When the file
* is deleted or moved out of it's parent, the callback is called with event
* CRAS_FILE_WAIT_EVENT_DELETED.
*
* Call cras_file_wait_destroy() to cancel the wait anytime and cleanup
* resources.
*
* Args:
* file_path - Path of the file or directory that must exist.
* flags - CRAS_FILE_WAIT_FLAG_* values bit-wise orred together. Set to
* CRAS_FILE_WAIT_FLAG_NONE for now.
* callback - Callback function to execute to notify of file existence.
* callback_context - Context pointer passed to the callback function.
* file_wait_out - Pointer to file wait structure that is initialized.
*
* Returns:
* - 0 for success, or negative on error.
* - On error cras_file_wait_destroy() need not be called.
*/
int cras_file_wait_create(const char *file_path, cras_file_wait_flag_t flags,
cras_file_wait_callback_t callback,
void *callback_context,
struct cras_file_wait **file_wait_out);
/* Returns the file-descriptor to poll for a file wait.
*
* Poll for POLLIN on this file decriptor. When there is data available, call
* cras_file_wait_continue() on the associated file_wait structure.
*
* Args:
* file_wait - The associated cras_file_wait structure initialized by
* cras_file_wait_start().
*
* Returns:
* Non-negative file descriptor number, or -EINVAL if the file_wait
* structure is NULL or otherwise invalid.
*/
int cras_file_wait_get_fd(struct cras_file_wait *file_wait);
/* Dispatch a file wait event.
*
* Call this function when the file descriptor from cras_file_wait_fd() has
* data ready (POLLIN). This function will call the callback provided to
* cras_file_wait_start when there is a relevant event.
*
* Args:
* file_wait - The associated cras_file_wait structure initialized by
* cras_file_wait_start().
*
* Returns:
* - 0 for success, negative on error.
* - -EAGAIN or -EWOULDBLOCK when this function would have blocked.
*/
int cras_file_wait_dispatch(struct cras_file_wait *file_wait);
/* Destroy a file wait structure.
*
* This function can be called to cleanup a cras_file_wait structure, and it
* will interrupt any wait that is in progress; the pointer is subsequently
* invalid.
*
* Args:
* file_wait - The cras_file_wait structure initialized by
* cras_file_wait_start();
*/
void cras_file_wait_destroy(struct cras_file_wait *file_wait);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* CRAS_FILE_WAIT_H_ */
|
