From cb76e4da84c61609c13e84c922f14a27b8348a36 Mon Sep 17 00:00:00 2001 From: Nikias Bassen Date: Tue, 13 May 2025 18:34:32 +0200 Subject: Add plist_new_unix_date, plist_get_unix_date_val, plist_set_unix_date_val functions These functions work with int64_t values representing a UNIX timestamp instead of using the 'MAC epoch'. They should be used instead of plist_new_date, plist_get_date_val, and plist_set_date_val, which are now marked deprecated and might be removed in a future version of libplist. --- include/plist/plist.h | 84 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 71 insertions(+), 13 deletions(-) (limited to 'include/plist/plist.h') diff --git a/include/plist/plist.h b/include/plist/plist.h index aff81e9..41af8ce 100644 --- a/include/plist/plist.h +++ b/include/plist/plist.h @@ -263,12 +263,11 @@ extern "C" /** * Create a new plist_t type #PLIST_DATE * - * @param sec the number of seconds since 01/01/2001 - * @param usec the number of microseconds + * @param sec The number of seconds since 01/01/1970 (UNIX timestamp) * @return the created item * @sa #plist_type */ - PLIST_API plist_t plist_new_date(int32_t sec, int32_t usec); + PLIST_API plist_t plist_new_unix_date(int64_t sec); /** * Create a new plist_t type #PLIST_UID @@ -775,10 +774,9 @@ extern "C" * This function does nothing if node is not of type #PLIST_DATE * * @param node the node - * @param sec a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001. - * @param usec a pointer to an int32_t variable. Represents the number of microseconds + * @param sec a pointer to an int64_t variable. Represents the number of seconds since 01/01/1970 (UNIX timestamp). */ - PLIST_API void plist_get_date_val(plist_t node, int32_t * sec, int32_t * usec); + PLIST_API void plist_get_unix_date_val(plist_t node, int64_t *sec); /** * Get the value of a #PLIST_UID node. @@ -867,10 +865,9 @@ extern "C" * Forces type of node to #PLIST_DATE * * @param node the node - * @param sec the number of seconds since 01/01/2001 - * @param usec the number of microseconds + * @param sec the number of seconds since 01/01/1970 (UNIX timestamp) */ - PLIST_API void plist_set_date_val(plist_t node, int32_t sec, int32_t usec); + PLIST_API void plist_set_unix_date_val(plist_t node, int64_t sec); /** * Set the value of a node. @@ -1213,16 +1210,15 @@ extern "C" /** * Helper function to compare the value of a PLIST_DATE node against - * a given set of seconds and fraction of a second since epoch. + * a given number of seconds since epoch (UNIX timestamp). * * @param datenode node of type PLIST_DATE - * @param cmpsec number of seconds since epoch to compare against - * @param cmpusec fraction of a second in microseconds to compare against + * @param cmpval Number of seconds to compare against (UNIX timestamp) * @return 0 if the node's date is equal to the supplied values, * 1 if the node's date is greater than the supplied values, * or -1 if the node's date is less than the supplied values. */ - PLIST_API int plist_date_val_compare(plist_t datenode, int32_t cmpsec, int32_t cmpusec); + PLIST_API int plist_unix_date_val_compare(plist_t datenode, int64_t cmpval); /** * Helper function to compare the value of a PLIST_STRING node against @@ -1382,6 +1378,68 @@ extern "C" */ PLIST_API const char* libplist_version(); + + /******************************************** + * * + * Deprecated API * + * * + ********************************************/ + + /** + * Create a new plist_t type #PLIST_DATE + * + * @deprecated Deprecated. Use plist_new_unix_date instead. + * + * @param sec the number of seconds since 01/01/2001 + * @param usec the number of microseconds + * @return the created item + * @sa #plist_type + */ + PLIST_WARN_DEPRECATED("use plist_new_unix_date instead") + PLIST_API plist_t plist_new_date(int32_t sec, int32_t usec); + + /** + * Get the value of a #PLIST_DATE node. + * This function does nothing if node is not of type #PLIST_DATE + * + * @deprecated Deprecated. Use plist_get_unix_date_val instead. + * + * @param node the node + * @param sec a pointer to an int32_t variable. Represents the number of seconds since 01/01/2001. + * @param usec a pointer to an int32_t variable. Represents the number of microseconds + */ + PLIST_WARN_DEPRECATED("use plist_get_unix_date_val instead") + PLIST_API void plist_get_date_val(plist_t node, int32_t * sec, int32_t * usec); + + /** + * Set the value of a node. + * Forces type of node to #PLIST_DATE + * + * @deprecated Deprecated. Use plist_set_unix_date_val instead. + * + * @param node the node + * @param sec the number of seconds since 01/01/2001 + * @param usec the number of microseconds + */ + PLIST_WARN_DEPRECATED("use plist_set_unix_date_val instead") + PLIST_API void plist_set_date_val(plist_t node, int32_t sec, int32_t usec); + + /** + * Helper function to compare the value of a PLIST_DATE node against + * a given set of seconds and fraction of a second since epoch. + * + * @deprecated Deprecated. Use plist_unix_date_val_compare instead. + * + * @param datenode node of type PLIST_DATE + * @param cmpsec number of seconds since epoch to compare against + * @param cmpusec fraction of a second in microseconds to compare against + * @return 0 if the node's date is equal to the supplied values, + * 1 if the node's date is greater than the supplied values, + * or -1 if the node's date is less than the supplied values. + */ + PLIST_WARN_DEPRECATED("use plist_unix_date_val_compare instead") + PLIST_API int plist_date_val_compare(plist_t datenode, int32_t cmpsec, int32_t cmpusec); + /*@}*/ #ifdef __cplusplus -- cgit v1.1-32-gdbae