Doxygen frindly comments

[yaz-moved-to-github.git] / include / yaz / marcdisp.h

diff --git a/include/yaz/marcdisp.h b/include/yaz/marcdisp.h
index 26984b2..0700b4d 100644 (file)
--- a/include/yaz/marcdisp.h
+++ b/include/yaz/marcdisp.h
@@ -1,5 +1,5 @@
-/*
- * Copyright (c) 1995-2007, Index Data
+/* This file is part of the YAZ toolkit.
+ * Copyright (C) 1995-2009 Index Data.

  * All rights reserved.
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
  * All rights reserved.
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:

@@ -24,7 +24,6 @@
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */

-/* $Id: marcdisp.h,v 1.25 2007-01-03 08:42:14 adam Exp $ */

 
 /**
  * \file marcdisp.h
 
 /**
  * \file marcdisp.h

@@ -40,6 +39,7 @@
 
 #include <yaz/nmem.h>
 #include <yaz/xmltypes.h>
 
 #include <yaz/nmem.h>
 #include <yaz/xmltypes.h>

+#include <yaz/z-opac.h>

 
 YAZ_BEGIN_CDECL
 
 
 YAZ_BEGIN_CDECL
 

@@ -65,14 +65,17 @@ YAZ_EXPORT void yaz_marc_xml(yaz_marc_t mt, int xmlmode);
 #define YAZ_MARC_MARCXML   3
 /** \brief Output format: ISO2709 */
 #define YAZ_MARC_ISO2709   4
 #define YAZ_MARC_MARCXML   3
 /** \brief Output format: ISO2709 */
 #define YAZ_MARC_ISO2709   4

-/** \brief Output format: MarcXchange */
+/** \brief Output format: MarcXchange (ISO25577) */

 #define YAZ_MARC_XCHANGE   5
 /** \brief Output format: check only (no marc output) */
 #define YAZ_MARC_CHECK  6
 
 #define YAZ_MARC_XCHANGE   5
 /** \brief Output format: check only (no marc output) */
 #define YAZ_MARC_CHECK  6
 

-/** \brief supply iconv handle for character set conversion .. */
+/** \brief set iconv handle for character set conversion */

 YAZ_EXPORT void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
 
 YAZ_EXPORT void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);
 

+/** \brief supply iconv handle for character set conversion */
+YAZ_EXPORT yaz_iconv_t yaz_marc_get_iconv(yaz_marc_t mt);
+

 /** \brief set debug level 
     \param mt handle
     \param level level, where 0=lowest, 1 more debug, 2 even more 
 /** \brief set debug level 
     \param mt handle
     \param level level, where 0=lowest, 1 more debug, 2 even more 

@@ -83,15 +86,15 @@ YAZ_EXPORT void yaz_marc_debug(yaz_marc_t mt, int level);
     \param mt marc handle
     \param buf input buffer
     \param bsize size of buffer or (-1 if "any size")
     \param mt marc handle
     \param buf input buffer
     \param bsize size of buffer or (-1 if "any size")

-    \param result result to be stored here (allocate before use!)
-    \param rsize size of result (set before calling)
+    \param result result to be stored here
+    \param rsize size of result (memory "owned" by yaz_marc_mt handle)

 
     Decodes MARC in buf of size bsize.
     On success, result in *result with size *rsize. 
     Returns -1 on error, or size of input record (>0) if OK
 */
 YAZ_EXPORT int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,
 
     Decodes MARC in buf of size bsize.
     On success, result in *result with size *rsize. 
     Returns -1 on error, or size of input record (>0) if OK
 */
 YAZ_EXPORT int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,

-                                   char **result, int *rsize);
+                                   const char **result, size_t *rsize);

 
 /** \brief decodes ISO2709/MARC buffer and stores result in WRBUF
     \param mt handle
 
 /** \brief decodes ISO2709/MARC buffer and stores result in WRBUF
     \param mt handle

@@ -106,20 +109,6 @@ YAZ_EXPORT int yaz_marc_decode_buf(yaz_marc_t mt, const char *buf, int bsize,
 YAZ_EXPORT int yaz_marc_decode_wrbuf(yaz_marc_t mt, const char *buf,
                                      int bsize, WRBUF wrbuf);
 
 YAZ_EXPORT int yaz_marc_decode_wrbuf(yaz_marc_t mt, const char *buf,
                                      int bsize, WRBUF wrbuf);
 

-/** \brief depricated */
-YAZ_EXPORT int marc_display(const char *buf, FILE *outf);
-/** \brief depricated */
-YAZ_EXPORT int marc_display_ex(const char *buf, FILE *outf, int debug);
-/** \brief depricated */
-YAZ_EXPORT int marc_display_exl(const char *buf, FILE *outf, int debug,
-                                int length);
-/** \brief depricated */
-YAZ_EXPORT int marc_display_wrbuf(const char *buf, WRBUF wr, int debug,
-                                  int bsize);
-/** \brief depricated */
-YAZ_EXPORT int yaz_marc_decode(const char *buf, WRBUF wr,
-                               int debug, int bsize, int xml);
-

 YAZ_EXPORT void yaz_marc_subfield_str(yaz_marc_t mt, const char *s);
 YAZ_EXPORT void yaz_marc_endline_str(yaz_marc_t mt, const char *s);
 
 YAZ_EXPORT void yaz_marc_subfield_str(yaz_marc_t mt, const char *s);
 YAZ_EXPORT void yaz_marc_endline_str(yaz_marc_t mt, const char *s);
 

@@ -173,6 +162,7 @@ int yaz_marc_read_line(yaz_marc_t mt,
                        void (*ungetbyte)(int b, void *client_data),
                        void *client_data);
 
                        void (*ungetbyte)(int b, void *client_data),
                        void *client_data);
 

+#if YAZ_HAVE_XML2

 /** \brief parses MARCXML/MarcXchange record from xmlNode pointer 
     \param mt handle
     \param ptr is a pointer to root xml node 
 /** \brief parses MARCXML/MarcXchange record from xmlNode pointer 
     \param mt handle
     \param ptr is a pointer to root xml node 

@@ -180,6 +170,7 @@ int yaz_marc_read_line(yaz_marc_t mt,
     Returns 0=OK, -1=ERROR
 */
 YAZ_EXPORT int yaz_marc_read_xml(yaz_marc_t mt, const xmlNode *ptr);
     Returns 0=OK, -1=ERROR
 */
 YAZ_EXPORT int yaz_marc_read_xml(yaz_marc_t mt, const xmlNode *ptr);

+#endif

 
 /** \brief writes record in line format
     \param mt handle
 
 /** \brief writes record in line format
     \param mt handle

@@ -197,7 +188,7 @@ YAZ_EXPORT int yaz_marc_write_line(yaz_marc_t mt, WRBUF wrbuf);
 */
 YAZ_EXPORT int yaz_marc_write_marcxml(yaz_marc_t mt, WRBUF wrbuf);
 
 */
 YAZ_EXPORT int yaz_marc_write_marcxml(yaz_marc_t mt, WRBUF wrbuf);
 

-/** \brief writes record in MarcXchange XML
+/** \brief writes record in MarcXchange XML (ISO25577)

     \param mt handle
     \param wrbuf WRBUF for output
     \param format record format (e.g. "MARC21")
     \param mt handle
     \param wrbuf WRBUF for output
     \param format record format (e.g. "MARC21")

@@ -225,6 +216,7 @@ YAZ_EXPORT int yaz_marc_write_iso2709(yaz_marc_t mt, WRBUF wrbuf);
 */  
 YAZ_EXPORT int yaz_marc_write_mode(yaz_marc_t mt, WRBUF wrbuf);
 
 */  
 YAZ_EXPORT int yaz_marc_write_mode(yaz_marc_t mt, WRBUF wrbuf);
 

+#if YAZ_HAVE_XML2

 /** \brief writes MARC record as libxml2 tree
     \param mt handle
     \param root_ptr pointer to record node
 /** \brief writes MARC record as libxml2 tree
     \param mt handle
     \param root_ptr pointer to record node

@@ -239,6 +231,7 @@ int yaz_marc_write_xml(yaz_marc_t mt, xmlNode **root_ptr,
                        const char *ns, 
                        const char *format,
                        const char *type);
                        const char *ns, 
                        const char *format,
                        const char *type);

+#endif

 
 /** \brief sets leader spec (for modifying bytes in 24 byte leader)
     \param mt handle
 
 /** \brief sets leader spec (for modifying bytes in 24 byte leader)
     \param mt handle

@@ -265,7 +258,7 @@ YAZ_EXPORT int yaz_marc_leader_spec(yaz_marc_t mt, const char *leader_spec);
     \param length_implementation length of implementation defined data
 */
 YAZ_EXPORT
     \param length_implementation length of implementation defined data
 */
 YAZ_EXPORT

-void yaz_marc_set_leader(yaz_marc_t mt, const char *leader_c,
+void yaz_marc_set_leader(yaz_marc_t mt, const char *leader,

                          int *indicator_length,
                          int *identifier_length,
                          int *base_address,
                          int *indicator_length,
                          int *identifier_length,
                          int *base_address,

@@ -309,6 +302,7 @@ void yaz_marc_add_controlfield(yaz_marc_t mt, const char *tag,
                                const char *data, size_t data_len);
 
 
                                const char *data, size_t data_len);
 
 

+#if YAZ_HAVE_XML2

 /** \brief adds controlfield to MARC structure using xml Nodes
     \param mt handle
     \param ptr_tag value of tag (TEXT xmlNode)
 /** \brief adds controlfield to MARC structure using xml Nodes
     \param mt handle
     \param ptr_tag value of tag (TEXT xmlNode)

@@ -317,7 +311,7 @@ void yaz_marc_add_controlfield(yaz_marc_t mt, const char *tag,
 YAZ_EXPORT
 void yaz_marc_add_controlfield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
                                    const xmlNode *ptr_data);
 YAZ_EXPORT
 void yaz_marc_add_controlfield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
                                    const xmlNode *ptr_data);

-
+#endif

 
 /** \brief adds datafield to MARC structure using strings
     \param mt handle
 
 /** \brief adds datafield to MARC structure using strings
     \param mt handle

@@ -329,6 +323,7 @@ YAZ_EXPORT
 void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
                             const char *indicator, size_t indicator_len);
 
 void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
                             const char *indicator, size_t indicator_len);
 

+#if YAZ_HAVE_XML2

 /** \brief adds datafield to MARC structure using xml Nodes
     \param mt handle
     \param ptr_tag value of tag (TEXT xmlNode)
 /** \brief adds datafield to MARC structure using xml Nodes
     \param mt handle
     \param ptr_tag value of tag (TEXT xmlNode)

@@ -338,7 +333,7 @@ void yaz_marc_add_datafield(yaz_marc_t mt, const char *tag,
 YAZ_EXPORT
 void yaz_marc_add_datafield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
                                 const char *indicator, size_t indicator_len);
 YAZ_EXPORT
 void yaz_marc_add_datafield_xml(yaz_marc_t mt, const xmlNode *ptr_tag,
                                 const char *indicator, size_t indicator_len);

-
+#endif

 
 /** \brief returns memory for MARC handle
     \param mt handle
 
 /** \brief returns memory for MARC handle
     \param mt handle

@@ -373,12 +368,33 @@ int yaz_marc_decode_formatstr(const char *arg);
 YAZ_EXPORT
 void yaz_marc_write_using_libxml2(yaz_marc_t mt, int enable);
 
 YAZ_EXPORT
 void yaz_marc_write_using_libxml2(yaz_marc_t mt, int enable);
 

+/** \brief Performs "pretty" display of OPAC record to WRBUF */
+YAZ_EXPORT void yaz_display_OPAC(WRBUF wrbuf, Z_OPACRecord *r, int flags);
+
+/** \brief Performs "pretty" display of OPAC record to WRBUF using marc_t */
+YAZ_EXPORT void yaz_opac_decode_wrbuf(yaz_marc_t mt, Z_OPACRecord *r, WRBUF wrbuf);
+
+
+/** \brief flushes records
+    \param mt handle
+    \param wr WRBUF for output
+    \retval 0 OK
+    \retval -1 ERROR
+*/  
+YAZ_EXPORT int yaz_marc_write_trailer(yaz_marc_t mt, WRBUF wr);
+
+/** \brief enables record collection output
+    \param mt handle
+*/  
+YAZ_EXPORT void yaz_marc_enable_collection(yaz_marc_t mt);
+

 YAZ_END_CDECL
 
 #endif
 /*
  * Local variables:
  * c-basic-offset: 4
 YAZ_END_CDECL
 
 #endif
 /*
  * Local variables:
  * c-basic-offset: 4

+ * c-file-style: "Stroustrup"

  * indent-tabs-mode: nil
  * End:
  * vim: shiftwidth=4 tabstop=8 expandtab
  * indent-tabs-mode: nil
  * End:
  * vim: shiftwidth=4 tabstop=8 expandtab