ZOOM.xs

   1 /* $Id: ZOOM.xs,v 1.16 2005-10-24 16:39:55 mike Exp $ */
   2
   3 #include "EXTERN.h"
   4 #include "perl.h"
   5 #include "XSUB.h"
   6
   7 #include <yaz/zoom.h>
   8 #include <yaz/xmalloc.h>
   9
  10 /* Used by the *_setl() functions */
  11 typedef char opaquechar;
  12
  13 /* Used as the return value of the *_getl() functions */
  14 struct datachunk {
  15         char *data;
  16         int len;
  17 };
  18
  19 /* Used to package Perl function-pointer and user-data together */
  20 struct callback_block {
  21         SV *function;
  22         SV *handle;
  23 };
  24
  25 /* The callback function used for ZOOM_options_set_callback().  I do
  26  * not claim to fully understand all the stack-hacking magic, and less
  27  * still the reference-counting/mortality stuff.  Accordingly, the
  28  * memory management here is best characterised as What I Could Get To
  29  * Work, More Or Less.
  30  */
  31 const char *__ZOOM_option_callback (void *handle, const char *name)
  32 {
  33         struct callback_block *cb = (struct callback_block*) handle;
  34         int count;
  35         SV *ret;
  36         char *s;
  37         char *res;
  38
  39         dSP;
  40
  41         ENTER;
  42         SAVETMPS;
  43
  44         PUSHMARK(SP);
  45         XPUSHs(cb->handle);
  46         XPUSHs(sv_2mortal(newSVpv(name, 0)));
  47         PUTBACK;
  48         /* Perl_sv_dump(0, cb->function); */
  49
  50         count = call_sv(cb->function, G_SCALAR);
  51
  52         SPAGAIN;
  53
  54         if (count != 1)
  55                 croak("callback function for ZOOM_options_get() returned %d values: should have returned exactly one", count);
  56
  57         ret = POPs;
  58         if (SvPOK(ret)) {
  59                 s = SvPV_nolen(ret);
  60                 /* ### `res' never gets freed!  I think it is
  61                  * impossible to solve this problem "correctly"
  62                  * because the ZOOM-C option callback interface is
  63                  * inadequate. */
  64                 res = xstrdup(s);
  65         } else {
  66                 res = 0;
  67         }
  68
  69         PUTBACK;
  70         FREETMPS;
  71         LEAVE;
  72
  73         return res;
  74 }
  75
  76
  77 MODULE = Net::Z3950::ZOOM               PACKAGE = Net::Z3950::ZOOM              PREFIX=ZOOM_
  78
  79 PROTOTYPES: ENABLE
  80
  81
  82 # TESTED
  83 ZOOM_connection
  84 ZOOM_connection_new(host, portnum)
  85         const char* host
  86         int portnum
  87
  88 # TESTED
  89 ZOOM_connection
  90 ZOOM_connection_create(options)
  91         ZOOM_options options
  92
  93 # TESTED
  94 void
  95 ZOOM_connection_connect(c, host, portnum)
  96         ZOOM_connection c
  97         const char* host
  98         int portnum
  99
 100 # TESTED
 101 void
 102 ZOOM_connection_destroy(c)
 103         ZOOM_connection c
 104
 105 # TESTED
 106 const char *
 107 ZOOM_connection_option_get(c, key)
 108         ZOOM_connection c
 109         const char *key
 110
 111 # TESTED
 112 struct datachunk
 113 ZOOM_connection_option_getl(c, key, len)
 114         ZOOM_connection c
 115         const char* key
 116         int &len
 117         CODE:
 118                 RETVAL.data = (char*) ZOOM_connection_option_getl(c, key, &len);
 119                 RETVAL.len = len;
 120         OUTPUT:
 121                 RETVAL
 122                 len
 123
 124 # TESTED
 125 void
 126 ZOOM_connection_option_set(c, key, val)
 127         ZOOM_connection c
 128         const char *key
 129         const char *val
 130
 131 # In ZOOM-C, the `val' parameter is const char*.  However, our typemap
 132 # treats this as T_PV, i.e. it's "known" that it points to a
 133 # NUL-terminated string.  Instead, then, I here use opaquechar*, which
 134 # is an opaque pointer.  The underlying C function can then use this
 135 # along with `len' to Do The Right Thing.
 136 #
 137 # TESTED
 138 void
 139 ZOOM_connection_option_setl(c, key, val, len)
 140         ZOOM_connection c
 141         const char* key
 142         opaquechar* val
 143         int len
 144
 145 # The reference parameters, `cp' and `addinfo', need to already have
 146 # values when this function is called, otherwise an "uninitialised
 147 # value" warning is generated.  As far as I can see, there is no way
 148 # around this: no way to specify in a prototype that an argument is
 149 # allowed to be undefined, for example.  Since these function will
 150 # never be called directly by well-behaved client code, but only by
 151 # our own wrapper classes, I think we can live with that.
 152 #
 153 # The poxing about with cpp and caddinfo is due to Perl XS's lack of
 154 # support for const char**, but who can blame it?  If you ask me, the
 155 # whole "const" thing was well-intentioned by ghastly mistake.
 156 #
 157 # TESTED
 158 int
 159 ZOOM_connection_error(c, cp, addinfo)
 160         ZOOM_connection c
 161         char* &cp
 162         char* &addinfo
 163         CODE:
 164                 const char *ccp, *caddinfo;
 165                 RETVAL = ZOOM_connection_error(c, &ccp, &caddinfo);
 166                 cp = (char*) ccp;
 167                 addinfo = (char*) caddinfo;
 168         OUTPUT:
 169                 RETVAL
 170                 cp
 171                 addinfo
 172
 173 # See comments for ZOOM_connection_error() above
 174 # TESTED
 175 int
 176 ZOOM_connection_error_x(c, cp, addinfo, diagset)
 177         ZOOM_connection c
 178         const char * &cp
 179         const char * &addinfo
 180         const char * &diagset
 181         CODE:
 182                 const char *ccp, *caddinfo, *cdset;
 183                 RETVAL = ZOOM_connection_error_x(c, &ccp, &caddinfo, &cdset);
 184                 cp = (char*) ccp;
 185                 addinfo = (char*) caddinfo;
 186                 diagset = (char*) cdset;
 187         OUTPUT:
 188                 RETVAL
 189                 cp
 190                 addinfo
 191                 diagset
 192
 193 # TESTED
 194 int
 195 ZOOM_connection_errcode(c)
 196         ZOOM_connection c
 197
 198 # TESTED
 199 const char *
 200 ZOOM_connection_errmsg(c)
 201         ZOOM_connection c
 202
 203 # TESTED
 204 const char *
 205 ZOOM_connection_addinfo(c)
 206         ZOOM_connection c
 207
 208 # TESTED
 209 const char *
 210 ZOOM_diag_str(error)
 211         int error
 212
 213 # UNTESTED
 214 int
 215 ZOOM_connection_last_event(cs)
 216         ZOOM_connection cs
 217
 218 # UNTESTED
 219 ZOOM_resultset
 220 ZOOM_connection_search(arg0, q)
 221         ZOOM_connection arg0
 222         ZOOM_query      q
 223
 224 # TESTED
 225 ZOOM_resultset
 226 ZOOM_connection_search_pqf(c, q)
 227         ZOOM_connection c
 228         const char *q
 229
 230 # TESTED
 231 void
 232 ZOOM_resultset_destroy(r)
 233         ZOOM_resultset r
 234
 235 # UNTESTED
 236 const char *
 237 ZOOM_resultset_option_get(r, key)
 238         ZOOM_resultset  r
 239         const char *    key
 240
 241 # UNTESTED
 242 void
 243 ZOOM_resultset_option_set(r, key, val)
 244         ZOOM_resultset  r
 245         const char *    key
 246         const char *    val
 247
 248 # TESTED
 249 size_t
 250 ZOOM_resultset_size(r)
 251         ZOOM_resultset r
 252
 253 # UNTESTED
 254 void
 255 ZOOM_resultset_records(r, recs, start, count)
 256         ZOOM_resultset  r
 257         ZOOM_record *   recs
 258         size_t  start
 259         size_t  count
 260
 261 # TESTED
 262 ZOOM_record
 263 ZOOM_resultset_record(s, pos)
 264         ZOOM_resultset s
 265         size_t pos
 266
 267 # UNTESTED
 268 ZOOM_record
 269 ZOOM_resultset_record_immediate(s, pos)
 270         ZOOM_resultset  s
 271         size_t  pos
 272
 273 # UNTESTED
 274 void
 275 ZOOM_resultset_cache_reset(r)
 276         ZOOM_resultset  r
 277
 278 # See "typemap" for discussion of the "const char *" return-type.
 279 #
 280 # TESTED
 281 ### but should use datachunk for in some (not all!) cases.
 282 const char *
 283 ZOOM_record_get(rec, type, len)
 284         ZOOM_record rec
 285         const char* type
 286         int &len
 287         OUTPUT:
 288                 RETVAL
 289                 len
 290
 291 # UNTESTED
 292 void
 293 ZOOM_record_destroy(rec)
 294         ZOOM_record     rec
 295
 296 # UNTESTED
 297 ZOOM_record
 298 ZOOM_record_clone(srec)
 299         ZOOM_record     srec
 300
 301 # UNTESTED
 302 ZOOM_query
 303 ZOOM_query_create()
 304
 305 # UNTESTED
 306 void
 307 ZOOM_query_destroy(s)
 308         ZOOM_query      s
 309
 310 # UNTESTED
 311 int
 312 ZOOM_query_cql(s, str)
 313         ZOOM_query      s
 314         const char *    str
 315
 316 # UNTESTED
 317 int
 318 ZOOM_query_prefix(s, str)
 319         ZOOM_query      s
 320         const char *    str
 321
 322 # UNTESTED
 323 int
 324 ZOOM_query_sortby(s, criteria)
 325         ZOOM_query      s
 326         const char *    criteria
 327
 328 # UNTESTED
 329 ZOOM_scanset
 330 ZOOM_connection_scan(c, startterm)
 331         ZOOM_connection c
 332         const char *    startterm
 333
 334 # UNTESTED
 335 const char *
 336 ZOOM_scanset_term(scan, pos, occ, len)
 337         ZOOM_scanset    scan
 338         size_t  pos
 339         int *   occ
 340         int *   len
 341
 342 # UNTESTED
 343 const char *
 344 ZOOM_scanset_display_term(scan, pos, occ, len)
 345         ZOOM_scanset    scan
 346         size_t  pos
 347         int *   occ
 348         int *   len
 349
 350 # UNTESTED
 351 size_t
 352 ZOOM_scanset_size(scan)
 353         ZOOM_scanset    scan
 354
 355 # UNTESTED
 356 void
 357 ZOOM_scanset_destroy(scan)
 358         ZOOM_scanset    scan
 359
 360 # UNTESTED
 361 const char *
 362 ZOOM_scanset_option_get(scan, key)
 363         ZOOM_scanset    scan
 364         const char *    key
 365
 366 # UNTESTED
 367 void
 368 ZOOM_scanset_option_set(scan, key, val)
 369         ZOOM_scanset    scan
 370         const char *    key
 371         const char *    val
 372
 373 # UNTESTED
 374 ZOOM_package
 375 ZOOM_connection_package(c, options)
 376         ZOOM_connection c
 377         ZOOM_options    options
 378
 379 # UNTESTED
 380 void
 381 ZOOM_package_destroy(p)
 382         ZOOM_package    p
 383
 384 # UNTESTED
 385 void
 386 ZOOM_package_send(p, type)
 387         ZOOM_package    p
 388         const char *    type
 389
 390 # UNTESTED
 391 const char *
 392 ZOOM_package_option_get(p, key)
 393         ZOOM_package    p
 394         const char *    key
 395
 396 # UNTESTED
 397 void
 398 ZOOM_package_option_set(p, key, val)
 399         ZOOM_package    p
 400         const char *    key
 401         const char *    val
 402
 403 # UNTESTED
 404 void
 405 ZOOM_resultset_sort(r, sort_type, sort_spec)
 406         ZOOM_resultset  r
 407         const char *    sort_type
 408         const char *    sort_spec
 409
 410 # We ignore the return value of ZOOM_options_set_callback(), since it
 411 # is always just the address of the __ZOOM_option_callback() function.
 412 # The information that we actually want -- the address of the Perl
 413 # function in the callback_block -- is unavailable to us, as the
 414 # underlying C function doesn't give the block back.
 415 #
 416 # TESTED
 417 void
 418 ZOOM_options_set_callback(opt, function, handle)
 419         ZOOM_options opt
 420         SV* function;
 421         SV* handle;
 422         CODE:
 423                 /* The tiny amount of memory allocated here is never
 424                  * released, as options_destroy() doesn't do anything
 425                  * to the callback information.  Not a big deal.
 426                  * Also, I have no idea how to drive the Perl "mortal"
 427                  * reference-counting stuff, so I am just allocating
 428                  * copies which also never get released.  Don't sue!
 429                  */
 430                 struct callback_block *block = (struct callback_block*)
 431                         xmalloc(sizeof *block);
 432                 block->function = function;
 433                 block->handle = handle;
 434                 SvREFCNT(block->function);
 435                 SvREFCNT(block->handle);
 436                 ZOOM_options_set_callback(opt, __ZOOM_option_callback,
 437                                           (void*) block);
 438
 439 # TESTED
 440 ZOOM_options
 441 ZOOM_options_create()
 442
 443 # TESTED
 444 ZOOM_options
 445 ZOOM_options_create_with_parent(parent)
 446         ZOOM_options parent
 447
 448 # TESTED
 449 ZOOM_options
 450 ZOOM_options_create_with_parent2(parent1, parent2)
 451         ZOOM_options parent1
 452         ZOOM_options parent2
 453
 454 # TESTED
 455 const char *
 456 ZOOM_options_get(opt, name)
 457         ZOOM_options opt
 458         const char* name
 459
 460 # TESTED
 461 struct datachunk
 462 ZOOM_options_getl(opt, name, len)
 463         ZOOM_options opt
 464         const char* name
 465         int &len
 466         CODE:
 467                 RETVAL.data = (char*) ZOOM_options_getl(opt, name, &len);
 468                 RETVAL.len = len;
 469         OUTPUT:
 470                 RETVAL
 471                 len
 472
 473 # TESTED
 474 void
 475 ZOOM_options_set(opt, name, v)
 476         ZOOM_options opt
 477         const char* name
 478         const char* v
 479
 480 # TESTED
 481 void
 482 ZOOM_options_setl(opt, name, value, len)
 483         ZOOM_options opt
 484         const char* name
 485         opaquechar* value
 486         int len
 487
 488 # TESTED
 489 void
 490 ZOOM_options_destroy(opt)
 491         ZOOM_options opt
 492
 493 # TESTED
 494 int
 495 ZOOM_options_get_bool(opt, name, defa)
 496         ZOOM_options opt
 497         const char* name
 498         int defa
 499
 500 # TESTED
 501 int
 502 ZOOM_options_get_int(opt, name, defa)
 503         ZOOM_options opt
 504         const char* name
 505         int defa
 506
 507 # TESTED
 508 void
 509 ZOOM_options_set_int(opt, name, value)
 510         ZOOM_options opt
 511         const char* name
 512         int value
 513
 514 # UNTESTED
 515 int
 516 ZOOM_event(no, cs)
 517         int     no
 518         ZOOM_connection *       cs
 519