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