Exposes config options in metadata_read and file_upload operations. C…

…loses #58
OuhscBbmc · Nov 2, 2014 · 5719413 · 5719413
1 parent bbcaa42
commit 5719413
Show file tree

Hide file tree

Showing 7 changed files with 33 additions and 40 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -6,7 +6,7 @@ Description: Encapsulates functions to streamline calls from R to the REDCap
     University.  The Application Programming Interface (API) offers an avenue
     to access and modify data programmatically, improving the capacity for
     literate and reproducible programming.
-Version: 0.5-19
+Version: 0.6-02
 Date: 2014-10-07
 Authors@R: c(person("Will", "Beasley", role = c("aut", "cre"), email =
     "[email protected]"), person("David", "Bard", role = "ctb"),

diff --git a/DocumentationPeek.pdf b/DocumentationPeek.pdf
diff --git a/NEWS b/NEWS
@@ -1,4 +1,9 @@
-Version 0.5 (Developed 2014-09-20 through 2014-10-09)
+Version 0.6 (Developed 2014-10-29 through ?)
+------------------------------------------------------------------------------
+New Features: 
+* The `config_options` in the `httr` package are exposed to the REDCapR user.  See issues #55 & #58; thanks to @rparrish and @nutterb for their contributions (https://github.com/OuhscBbmc/REDCapR/issues/55 & https://github.com/OuhscBbmc/REDCapR/issues/58).
+
+Version 0.5 (Developed 2014-09-20 through 2014-10-19)
 ------------------------------------------------------------------------------
 New Features: 
 * `redcap_metadata_read` are tested and public.

diff --git a/R/redcap_metadata_read.R b/R/redcap_metadata_read.R
@@ -13,8 +13,7 @@
 #' @param fields An array, where each element corresponds to a desired project field.  Optional.
 #' @param fields_collapsed A single string, where the desired field names are separated by commas.  Optional.
 #' @param verbose A boolean value indicating if \code{message}s should be printed to the R console during the operation.  The verbose output might contain sensitive information (\emph{e.g.} PHI), so turn this off if the output might be visible somewhere public. Optional.
-#' @param cert_location  If present, this string should point to the location of the cert files required for SSL verification.  If the value is missing or NULL, the server's identity will be verified using a recent CA bundle from the \href{http://curl.haxx.se}{cURL website}.  See the details below. Optional.
-#' @param sslversion The SSL version for curl. The default is 3. Set to NULL if your server has disabled SSL v3.
+#' @param config_options  A list of options to pass to \code{POST} method in the \code{httr} package.  See the details in \code{redcap_read_oneshot()} Optional.
 #' 
 #' @return Currently, a list is returned with the following elements,
 #' \enumerate{
@@ -48,7 +47,7 @@
 redcap_metadata_read <- function( 
                          redcap_uri, token, forms=NULL, forms_collapsed="", 
                          fields=NULL, fields_collapsed="", 
-                         verbose=TRUE, cert_location=NULL, sslversion=3 ) {  
+                         verbose=TRUE, config_options=NULL ) {  
   #TODO: NULL verbose parameter pulls from getOption("verbose")
   #TODO: warns if any requested fields aren't entirely lowercase.
 
@@ -67,13 +66,14 @@ redcap_metadata_read <- function(
   if( nchar(fields_collapsed)==0 )
     fields_collapsed <- ifelse(is.null(fields), "", paste0(fields, collapse=",")) #This is an empty string if `fields` is NULL.
 
-  if( missing( cert_location ) | is.null(cert_location) | (length(cert_location)==0))
+  if( missing( config_options ) | is.null(config_options) ) {
     cert_location <- system.file("ssl_certs/mozilla_ca_root.crt", package="REDCapR")
-
-  if( !base::file.exists(cert_location) )
+    
+    if( !base::file.exists(cert_location) )
       stop(paste0("The file specified by `cert_location`, (", cert_location, ") could not be found."))
-
-  config_options <- list(cainfo=cert_location, sslversion=sslversion)
+
+    config_options <- list(cainfo=cert_location)
+  }
 
   post_body <- list(
     token = token,

diff --git a/R/redcap_upload_file_oneshot.R b/R/redcap_upload_file_oneshot.R
@@ -13,8 +13,7 @@
 #' @param field The name of the field where the file is saved in REDCap. Required
 #' @param event The name of the event where the file is saved in REDCap. Optional
 #' @param verbose A boolean value indicating if \code{message}s should be printed to the R console during the operation.  Optional.
-#' @param cert_location  If present, this string should point to the location of the cert files required for SSL verification.  If the value is missing or NULL, the server's identity will be verified using a recent CA bundle from the \href{http://curl.haxx.se}{cURL website}.  See the details below. Optional.
-#' @param sslversion The SSL version for curl. The default is 3. Set to NULL if your server has disabled SSL v3.
+#' @param config_options  A list of options to pass to \code{POST} method in the \code{httr} package.  See the details below. Optional.
 #' 
 #' @return Currently, a list is returned with the following elements,
 #' \enumerate{
@@ -65,7 +64,7 @@
 #' } 
 #' }
 
-redcap_upload_file_oneshot <- function( file_name, record, redcap_uri, token, field, event="", verbose=TRUE, cert_location=NULL, sslversion=3 ) {
+redcap_upload_file_oneshot <- function( file_name, record, redcap_uri, token, field, event="", verbose=TRUE, config_options=NULL ) {
 	start_time <- Sys.time()
 
 	if( missing(file_name) | is.null(file_name) )
@@ -80,13 +79,14 @@ redcap_upload_file_oneshot <- function( file_name, record, redcap_uri, token, fi
 	if( missing(token) )
 		stop("The required parameter `token` was missing from the call to `redcap_upload_file_oneshot()`.")     
 
-	if( missing( cert_location ) | is.null(cert_location) ) 
-		cert_location <- system.file("ssl_certs/mozilla_ca_root.crt", package="REDCapR")
-
-	if( !base::file.exists(cert_location) )
-		stop(paste0("The file specified by `cert_location`, (", cert_location, ") could not be found."))
-
-	config_options <- list(cainfo=cert_location, sslversion=sslversion)
+  if( missing( config_options ) | is.null(config_options) ) {
+    cert_location <- system.file("ssl_certs/mozilla_ca_root.crt", package="REDCapR")
+
+    if( !base::file.exists(cert_location) )
+      stop(paste0("The file specified by `cert_location`, (", cert_location, ") could not be found."))
+
+    config_options <- list(cainfo=cert_location)
+  }
 
 	if( verbose )
 	  message("Preparing to upload the file `", file_name, "`.")

diff --git a/man/redcap_metadata_read.Rd b/man/redcap_metadata_read.Rd
@@ -5,7 +5,7 @@
 \usage{
 redcap_metadata_read(redcap_uri, token, forms = NULL, forms_collapsed = "",
   fields = NULL, fields_collapsed = "", verbose = TRUE,
-  cert_location = NULL, sslversion = 3)
+  config_options = NULL)
 }
 \arguments{
   \item{redcap_uri}{The URI (uniform resource identifier)
@@ -33,15 +33,9 @@ redcap_metadata_read(redcap_uri, token, forms = NULL, forms_collapsed = "",
   if the output might be visible somewhere public.
   Optional.}
 
-  \item{cert_location}{If present, this string should point
-  to the location of the cert files required for SSL
-  verification.  If the value is missing or NULL, the
-  server's identity will be verified using a recent CA
-  bundle from the \href{http://curl.haxx.se}{cURL website}.
-  See the details below. Optional.}
-
-  \item{sslversion}{The SSL version for curl. The default
-  is 3. Set to NULL if your server has disabled SSL v3.}
+  \item{config_options}{A list of options to pass to
+  \code{POST} method in the \code{httr} package.  See the
+  details in \code{redcap_read_oneshot()} Optional.}
 }
 \value{
 Currently, a list is returned with the following elements,

diff --git a/man/redcap_upload_file_oneshot.Rd b/man/redcap_upload_file_oneshot.Rd
@@ -4,7 +4,7 @@
 \title{Upload a file into to a REDCap project record.}
 \usage{
 redcap_upload_file_oneshot(file_name, record, redcap_uri, token, field,
-  event = "", verbose = TRUE, cert_location = NULL, sslversion = 3)
+  event = "", verbose = TRUE, config_options = NULL)
 }
 \arguments{
   \item{file_name}{The name of the relative or full file to
@@ -29,15 +29,9 @@ redcap_upload_file_oneshot(file_name, record, redcap_uri, token, field,
   \code{message}s should be printed to the R console during
   the operation.  Optional.}
 
-  \item{cert_location}{If present, this string should point
-  to the location of the cert files required for SSL
-  verification.  If the value is missing or NULL, the
-  server's identity will be verified using a recent CA
-  bundle from the \href{http://curl.haxx.se}{cURL website}.
-  See the details below. Optional.}
-
-  \item{sslversion}{The SSL version for curl. The default
-  is 3. Set to NULL if your server has disabled SSL v3.}
+  \item{config_options}{A list of options to pass to
+  \code{POST} method in the \code{httr} package.  See the
+  details below. Optional.}
 }
 \value{
 Currently, a list is returned with the following elements,