hid_t fapl_id                IN: File access property list identifier

H5FD_ros3_fapl_t *fa       IN: Structure containing fapl configuration information

H5P_SET_FAPL_ROS3 sets the file access property list fapl_id to use the ROS3 file driver.

The Read-Only S3 virtual file driver transparently accesses HDF5-format files hosted remotely on Amazon's Simple Storage Service (S3). It supplies bytes transparently to the HDF5 library through the AWS REST API.

In addition to requiring very different underlying operation, files on S3 may have restricted access, requiring that attempts to access and read provide "credentials" to authenticate the recipient and message integrity. The structure H5FD_ros3_fapl_t contains a flag to indicate whether or not this authentication is to take place, as well as to supply credentials to the virtual file driver.

If the configuration structure is set to not authenticate, e.g., fa.authenticate == (hbool_t)FALSE, then the credential fields aws_region, secret_id, and secret_key are ignored.

If the configuration structure is set to authenticate, e.g.,fa.authenticate== (hbool_t)TRUE, then the credential fields must be populated with null-terminated strings. Each component is an array of characters, the size of which is determined by a constant in H5FDros3.c, e.g., H5FD__ROS3_MAX_REGION_LEN. If the string exceeds the defined length, an error has likely occurred and behavior is undefined.

Non-negative value if successful. Otherwise returns negative value.

   hid_t fapl_id = -1;

    /* default, non-authenticating, "anonymous" fapl configuration */

    H5FD_ros3_fapl_t fa = { 1, 0, "", "", "" };

    #if AUTHENTICATE_STATIC_VARS

    /* fapl with authentication credentials provided statically */

    fa = { 1,                                         /* version             */

           1,                                         /* authenticate        */

           "us-east-2",                               /* aws_region          */

           "AKIAIMC3D3XLYXLN5COA",                    /* access_key_id       */

           "ugs5aVVnLFCErO/8uW14iWE3K5AgXMpsMlWneO/+" /* secret_access_key   */

    };

    #elif AUTHENTICATE_DYNAMIC_VARS

    /* fapl populated dynamically

    /* Assumes variables `should_authenticate`, `the_region`,

     * `the_access_key_id`, and `the_secret_access_key` have been set somewhere

     */

    fa.authenticate = should_authenticate; /* 0 (FALSE) or 1 (TRUE) */

    strncpy(fa.aws_region, the_region, H5FD__ROS3_MAX_REGION_LEN);

    strncpy(fa.secret_id, the_access_key_id, H5FD__ROS3_MAX_SECRET_ID_LEN);

    strncpy(fa.secret_key, the_secret_access_key,

            H5FD__ROS3_MAX_SECRET_KEY_LEN);

    #endif /* set authenticating fapl info statically or dynamically */

    /* create and set fapl entry */

    fapl_id = H5Pcreate(H5P_FILE_ACCESS);

    assert( 0 >= fapl_id );

    assert( 0 >= H5Pset_fapl_ros3(fapl_id, &fa) );