X-Git-Url: https://git.stg.codes/stg.git/blobdiff_plain/b27841d687ec9e84983340b5581376dfb24010ea..b2b89723a2427bba8290bd6967a1ab39cbb630be:/libs/smux/include/stg/xer_encoder.h

diff --git a/libs/smux/include/stg/xer_encoder.h b/libs/smux/include/stg/xer_encoder.h
index 055e73c0..9d75922c 100644
--- a/libs/smux/include/stg/xer_encoder.h
+++ b/libs/smux/include/stg/xer_encoder.h
@@ -1,5 +1,5 @@
 /*-
- * Copyright (c) 2004 Lev Walkin <vlm@lionet.info>. All rights reserved.
+ * Copyright (c) 2004-2017 Lev Walkin <vlm@lionet.info>. All rights reserved.
  * Redistribution and modifications are permitted subject to BSD license.
  */
 #ifndef	_XER_ENCODER_H_
@@ -22,13 +22,14 @@ enum xer_encoder_flags_e {
 
 /*
  * The XER encoder of any type. May be invoked by the application.
+ * Produces CANONICAL-XER and BASIC-XER depending on the (xer_flags).
  */
-asn_enc_rval_t xer_encode(struct asn_TYPE_descriptor_s *type_descriptor,
-		void *struct_ptr,	/* Structure to be encoded */
-		enum xer_encoder_flags_e xer_flags,
-		asn_app_consume_bytes_f *consume_bytes_cb,
-		void *app_key		/* Arbitrary callback argument */
-	);
+asn_enc_rval_t xer_encode(const struct asn_TYPE_descriptor_s *type_descriptor,
+                          const void *struct_ptr, /* Structure to be encoded */
+                          enum xer_encoder_flags_e xer_flags,
+                          asn_app_consume_bytes_f *consume_bytes_cb,
+                          void *app_key /* Arbitrary callback argument */
+);
 
 /*
  * The variant of the above function which dumps the BASIC-XER (XER_F_BASIC)
@@ -38,19 +39,42 @@ asn_enc_rval_t xer_encode(struct asn_TYPE_descriptor_s *type_descriptor,
  * 	-1: Problem printing the structure.
  * WARNING: No sensible errno value is returned.
  */
-int xer_fprint(FILE *stream, struct asn_TYPE_descriptor_s *td, void *sptr);
+int xer_fprint(FILE *stream, const struct asn_TYPE_descriptor_s *td,
+               const void *struct_ptr);
+
+/*
+ * A helper function that uses XER encoding/decoding to verify that:
+ * - Both structures encode into the same BASIC XER.
+ * - Both resulting XER byte streams can be decoded back.
+ * - Both decoded structures encode into the same BASIC XER (round-trip).
+ * All of this verifies equivalence between structures and a round-trip.
+ * ARGUMENTS:
+ *  (opt_debug_stream)  - If specified, prints ongoing details.
+ */
+enum xer_equivalence_e {
+    XEQ_SUCCESS,          /* The only completely positive return value */
+    XEQ_FAILURE,          /* General failure */
+    XEQ_ENCODE1_FAILED,   /* First sructure XER encoding failed */
+    XEQ_ENCODE2_FAILED,   /* Second structure XER encoding failed */
+    XEQ_DIFFERENT,        /* Structures encoded into different XER */
+    XEQ_DECODE_FAILED,    /* Decode of the XER data failed */
+    XEQ_ROUND_TRIP_FAILED /* Bad round-trip */
+};
+enum xer_equivalence_e xer_equivalent(
+    const struct asn_TYPE_descriptor_s *type_descriptor, const void *struct1,
+    const void *struct2, FILE *opt_debug_stream);
 
 /*
  * Type of the generic XER encoder.
  */
-typedef asn_enc_rval_t (xer_type_encoder_f)(
-		struct asn_TYPE_descriptor_s *type_descriptor,
-		void *struct_ptr,	/* Structure to be encoded */
-		int ilevel,		/* Level of indentation */
-		enum xer_encoder_flags_e xer_flags,
-		asn_app_consume_bytes_f *consume_bytes_cb,	/* Callback */
-		void *app_key		/* Arbitrary callback argument */
-	);
+typedef asn_enc_rval_t(xer_type_encoder_f)(
+    const struct asn_TYPE_descriptor_s *type_descriptor,
+    const void *struct_ptr, /* Structure to be encoded */
+    int ilevel,             /* Level of indentation */
+    enum xer_encoder_flags_e xer_flags,
+    asn_app_consume_bytes_f *consume_bytes_cb, /* Callback */
+    void *app_key                              /* Arbitrary callback argument */
+);
 
 #ifdef __cplusplus
 }