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, 77 cras_file_wait_flag_t flags, 78 cras_file_wait_callback_t callback, 79 void *callback_context, 80 struct cras_file_wait **file_wait_out); 81 82 /* Returns the file-descriptor to poll for a file wait. 83 * 84 * Poll for POLLIN on this file decriptor. When there is data available, call 85 * cras_file_wait_continue() on the associated file_wait structure. 86 * 87 * Args: 88 * file_wait - The associated cras_file_wait structure initialized by 89 * cras_file_wait_start(). 90 * 91 * Returns: 92 * Non-negative file descriptor number, or -EINVAL if the file_wait 93 * structure is NULL or otherwise invalid. 94 */ 95 int cras_file_wait_get_fd(struct cras_file_wait *file_wait); 96 97 /* Dispatch a file wait event. 98 * 99 * Call this function when the file descriptor from cras_file_wait_fd() has 100 * data ready (POLLIN). This function will call the callback provided to 101 * cras_file_wait_start when there is a relevant event. 102 * 103 * Args: 104 * file_wait - The associated cras_file_wait structure initialized by 105 * cras_file_wait_start(). 106 * 107 * Returns: 108 * - 0 for success, non-zero on error. 109 * - -EAGAIN or -EWOULDBLOCK when this function would have blocked. 110 */ 111 int cras_file_wait_dispatch(struct cras_file_wait *file_wait); 112 113 /* Destroy a file wait structure. 114 * 115 * This function can be called to cleanup a cras_file_wait structure, and it 116 * will interrupt any wait that is in progress; the pointer is subsequently 117 * invalid. 118 * 119 * Args: 120 * file_wait - The cras_file_wait structure initialized by 121 * cras_file_wait_start(); 122 */ 123 void cras_file_wait_destroy(struct cras_file_wait *file_wait); 124 125 #ifdef __cplusplus 126 } /* extern "C" */ 127 #endif 128 129 #endif /* CRAS_FILE_WAIT_H_ */ 130