renames following review

rename dcm_filehandle_read_pixeldata() as dcm_filehandle_prepare_read_frame()

rename dcm_filehandle_get_metadata() as dcm_filehandle_get_metadata_subset()

revise docs and tests

Author: jcupitt

doc/source/usage.rst

@@ -19,8 +19,8 @@ The `File Meta Information
 can be accessed via :c:func:`dcm_filehandle_get_file_meta()`.
 
 The principal metadata of the Data Set can be accessed via
-:c:func:`dcm_filehandle_get_metadata()`. This function will stop read on tags
-which are likely to take a long time to process.
+:c:func:`dcm_filehandle_get_metadata_subset()`. This function will stop
+read on tags which are likely to take a long time to process.
 
 You can read all metadata and control read stop using a sequence of calls to
 :c:func:`dcm_filehandle_read_metadata()`.
@@ -238,7 +238,8 @@ printing an element to standard output:
             return 1;
         }
 
-        const DcmDataSet *metadata = dcm_filehandle_get_metadata(&error, filehandle);
+        const DcmDataSet *metadata =
+            dcm_filehandle_get_metadata_subset(&error, filehandle);
         if (metadata == NULL) {
             dcm_error_log(error);
             dcm_error_clear(&error);

include/dicom/dicom.h

@@ -1701,10 +1701,14 @@ DcmDataSet *dcm_filehandle_read_metadata(DcmError **error,
                                          const uint32_t *stop_tags);
 
 /**
- * Get metadata from a File.
+ * Get a fast subset of metadata from a File.
  *
- * Gets the File's metadata and saves it in the File handle. Returns a
- * reference to this internal copy of the File metadata.
+ * Gets a subset of the File's metadata and saves it in the File handle.
+ * Returns a reference to this internal copy of the File metadata.
+ *
+ * The subset is the part of the DICOM metadata that can be read quickly. It
+ * is missing tags such as PerFrameFunctionalGroupSequence. Use
+ * dcm_filehandle_read_metadata() if you need all file metadata.
  *
  * The return result must not be destroyed. Make a clone of it with
  * :c:func:`dcm_dataset_clone()` if you need it to remain valid after
@@ -1721,8 +1725,8 @@ DcmDataSet *dcm_filehandle_read_metadata(DcmError **error,
  * :return: metadata
  */
 DCM_EXTERN
-const DcmDataSet *dcm_filehandle_get_metadata(DcmError **error,
-                                              DcmFilehandle *filehandle);
+const DcmDataSet *dcm_filehandle_get_metadata_subset(DcmError **error,
+                                                     DcmFilehandle *filehandle);
 
 /**
  * Read everything necessary to fetch frames from the file.
@@ -1747,8 +1751,8 @@ const DcmDataSet *dcm_filehandle_get_metadata(DcmError **error,
  * :return: true on success
  */
 DCM_EXTERN
-bool dcm_filehandle_read_pixeldata(DcmError **error,
-                                   DcmFilehandle *filehandle);
+bool dcm_filehandle_prepare_read_frame(DcmError **error,
+                                       DcmFilehandle *filehandle);
 
 /**
  * Read an individual Frame from a File.

src/dicom-file.c

@@ -757,8 +757,8 @@ DcmDataSet *dcm_filehandle_read_metadata(DcmError **error,
 }
 
 
-const DcmDataSet *dcm_filehandle_get_metadata(DcmError **error,
-                                              DcmFilehandle *filehandle)
+const DcmDataSet *dcm_filehandle_get_metadata_subset(DcmError **error,
+                                                     DcmFilehandle *filehandle)
 {
     // we stop on any of the tags that start a huge group that
     // would take a long time to parse
@@ -939,12 +939,12 @@ static bool read_skip_to_index(DcmError **error,
 }
 
 
-bool dcm_filehandle_read_pixeldata(DcmError **error,
-                                   DcmFilehandle *filehandle)
+bool dcm_filehandle_prepare_read_frame(DcmError **error,
+                                       DcmFilehandle *filehandle)
 {
     if (filehandle->offset_table == NULL) {
         // move to the first of our stop tags
-        if (dcm_filehandle_get_metadata(error, filehandle) == NULL) {
+        if (dcm_filehandle_get_metadata_subset(error, filehandle) == NULL) {
             return false;
         }
 
@@ -1030,7 +1030,7 @@ DcmFrame *dcm_filehandle_read_frame(DcmError **error,
 {
     dcm_log_debug("Read frame number #%u.", frame_number);
 
-    if (!dcm_filehandle_read_pixeldata(error, filehandle)) {
+    if (!dcm_filehandle_prepare_read_frame(error, filehandle)) {
         return NULL;
     }
 
@@ -1091,7 +1091,7 @@ DcmFrame *dcm_filehandle_read_frame_position(DcmError **error,
 {
     dcm_log_debug("Read frame position (%u, %u)", column, row);
 
-    if (!dcm_filehandle_read_pixeldata(error, filehandle)) {
+    if (!dcm_filehandle_prepare_read_frame(error, filehandle)) {
         return NULL;
     }
 

tests/check_dicom.c

@@ -679,7 +679,8 @@ START_TEST(test_file_sm_image_metadata)
     free(file_path);
     ck_assert_ptr_nonnull(filehandle);
 
-    const DcmDataSet *metadata = dcm_filehandle_get_metadata(NULL, filehandle);
+    const DcmDataSet *metadata =
+        dcm_filehandle_get_metadata_subset(NULL, filehandle);
     ck_assert_ptr_nonnull(metadata);
 
     // SOP Class UID
@@ -705,10 +706,11 @@ START_TEST(test_file_sm_image_frame)
     free(file_path);
     ck_assert_ptr_nonnull(filehandle);
 
-    const DcmDataSet *metadata = dcm_filehandle_get_metadata(NULL, filehandle);
+    const DcmDataSet *metadata =
+        dcm_filehandle_get_metadata_subset(NULL, filehandle);
     ck_assert_ptr_nonnull(metadata);
 
-    ck_assert_int_ne(dcm_filehandle_read_pixeldata(NULL, filehandle), 0);
+    ck_assert_int_ne(dcm_filehandle_prepare_read_frame(NULL, filehandle), 0);
 
     DcmFrame *frame = dcm_filehandle_read_frame(NULL,
                                                 filehandle,