#' @title Get the logging of a project.

#'

#' @description This function reads the available logging messages from

#'   REDCap an returns them as a [base::data.frame()].

#'

#' @param redcap_uri The URI (uniform resource identifier) of the REDCap

#' project.  Required.

#' @param token The user-specific string that serves as the password for a

#' project.  Required.

#' @param log_begin_date Return the events occurring after midnight of this

#' date.

#' Defaults to the past week; this default mimics the behavior in the browser

#' and also reduces the strain on your server.

#' @param log_end_date Return the events occurring before 24:00 of this date.

#' Defaults to today.

#' @param record Return the events belonging only to specific record

#' (referring to an existing record name).

#' Defaults to `NULL` which returns

#' logging activity related to all records.

#' If a record value passed, it must be a single value.

#' @param user Return the events belonging only to specific user

#' (referring to an existing username).

#' Defaults to `NULL` which returns

#' logging activity related to all users.

#' If a user value passed, it must be a single value.

#' @param http_response_encoding  The encoding value passed to

#' [httr::content()].  Defaults to 'UTF-8'.

#' @param locale a [readr::locale()] object to specify preferences like

#' number, date, and time formats.  This object is passed to

#' [`readr::read_csv()`].  Defaults to [readr::default_locale()].

#' @param verbose A boolean value indicating if `message`s should be printed

#' to the R console during the operation.  The verbose output might contain

#' sensitive information (*e.g.* PHI), so turn this off if the output might

#' be visible somewhere public. Optional.

#' @param config_options  A list of options to pass to `POST` method in the

#' `httr` package.

#'

#' @return Currently, a list is returned with the following elements:

#' * `data`: An R [base::data.frame()] of all data access groups of the project.

#' * `success`: A boolean value indicating if the operation was apparently

#' successful.

#' * `status_codes`: A collection of

#' [http status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes),

#' separated by semicolons.  There is one code for each batch attempted.

#' * `outcome_messages`: A collection of human readable strings indicating the

#' operations' semicolons.  There is one code for each batch attempted.  In an

#' unsuccessful operation, it should contain diagnostic information.

#' * `elapsed_seconds`: The duration of the function.

#'

#' @author Jonathan M. Mang, Will Beasley

#' @references The official documentation can be found on the 'API Help Page'

#' and 'API Examples' pages on the REDCap wiki (*i.e.*,

#' https://community.projectredcap.org/articles/456/api-documentation.html

#' and

#' https://community.projectredcap.org/articles/462/api-examples.html).

#' If you do not have an account for the wiki, please ask your campus REDCap

#' administrator to send you the static material.

#'

#' @examples

#' \dontrun{

#' uri          <- "https://bbmc.ouhsc.edu/redcap/api/"

#' token        <- "9A81268476645C4E5F03428B8AC3AA7B"

#'

#' ds_last_week <- REDCapR::redcap_log_read(redcap_uri=uri, token=token)$data

#' head(ds_last_week)

#'

#' ds_one_day <-

#'   REDCapR::redcap_log_read(

#'     redcap_uri     = uri,

#'     token          = token,

#'     log_begin_date = as.Date("2020-08-10"),

#'     log_end_date   = as.Date("2020-08-10")

#'   )$data

#' head(ds_one_day)

#'

#' ds_one_day_single_record_single_user <-

#'   REDCapR::redcap_log_read(

#'     redcap_uri     = uri,

#'     token          = token,

#'     log_begin_date = as.Date("2021-07-11"),

#'     log_end_date   = as.Date("2021-07-11"),

#'     record         = as.character(3),

#'     user           = "unittestphifree"

#'   )$data

#' head(ds_one_day_single_record_single_user)

#' }

#' @export

redcap_log_read <- function(

  redcap_uri,

  token,

  log_begin_date                = Sys.Date() - 7L,

  log_end_date                  = Sys.Date(),

  record                        = NULL,

  user                          = NULL,

  http_response_encoding        = "UTF-8",

  locale                        = readr::default_locale(),

  verbose                       = TRUE,

  config_options                = NULL

) {

  )

  # This is the important line that communicates with the REDCap server.

  )

      # Convert the raw text to a dataset.

        ) %>%

      # Don't print the warning in the try block.  Print it below,

      #   where it's under the control of the caller.

    )

      )

      # If an operation is successful, the `raw_text` is no longer returned to

      #   save RAM.  The content is not really necessary with httr's status

      #   message exposed.

    } else { # ds doesn't exist as a data.frame.

      # nocov start

      # Override the 'success' determination from the http status code.

      #   and return an empty data.frame.

      kernel$success   <- FALSE

      ds               <- data.frame()

      outcome_message  <- sprintf(

        "The REDCap log export failed.  The http status code was %i.  The 'raw_text' returned was '%s'.",

        kernel$status_code,

        kernel$raw_text

      )

      # nocov end

    }

  } else { # kernel fails

    } else {

      )

    }

  }

  )

}