Home | History | Annotate | Download | only in common 
      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