ZOOM.xs

   1 /* $Id: ZOOM.xs,v 1.32 2005-12-19 13:46:11 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                 {
 165                 const char *ccp, *caddinfo;
 166                 RETVAL = ZOOM_connection_error(c, &ccp, &caddinfo);
 167                 cp = (char*) ccp;
 168                 addinfo = (char*) caddinfo;
 169                 }
 170         OUTPUT:
 171                 RETVAL
 172                 cp
 173                 addinfo
 174
 175 # See comments for ZOOM_connection_error() above
 176 # TESTED
 177 int
 178 ZOOM_connection_error_x(c, cp, addinfo, diagset)
 179         ZOOM_connection c
 180         const char * &cp
 181         const char * &addinfo
 182         const char * &diagset
 183         CODE:
 184                 {
 185                 const char *ccp, *caddinfo, *cdset;
 186                 RETVAL = ZOOM_connection_error_x(c, &ccp, &caddinfo, &cdset);
 187                 cp = (char*) ccp;
 188                 addinfo = (char*) caddinfo;
 189                 diagset = (char*) cdset;
 190                 }
 191         OUTPUT:
 192                 RETVAL
 193                 cp
 194                 addinfo
 195                 diagset
 196
 197 # TESTED
 198 int
 199 ZOOM_connection_errcode(c)
 200         ZOOM_connection c
 201
 202 # TESTED
 203 const char *
 204 ZOOM_connection_errmsg(c)
 205         ZOOM_connection c
 206
 207 # TESTED
 208 const char *
 209 ZOOM_connection_addinfo(c)
 210         ZOOM_connection c
 211
 212 # TESTED
 213 const char *
 214 ZOOM_connection_diagset(c)
 215         ZOOM_connection c
 216
 217 # TESTED
 218 const char *
 219 ZOOM_diag_str(error)
 220         int error
 221
 222 # TESTED
 223 ZOOM_resultset
 224 ZOOM_connection_search(arg0, q)
 225         ZOOM_connection arg0
 226         ZOOM_query q
 227
 228 # TESTED
 229 ZOOM_resultset
 230 ZOOM_connection_search_pqf(c, q)
 231         ZOOM_connection c
 232         const char *q
 233
 234 # TESTED
 235 void
 236 ZOOM_resultset_destroy(r)
 237         ZOOM_resultset r
 238
 239 # TESTED
 240 const char *
 241 ZOOM_resultset_option_get(r, key)
 242         ZOOM_resultset r
 243         const char* key
 244
 245 # TESTED
 246 void
 247 ZOOM_resultset_option_set(r, key, val)
 248         ZOOM_resultset r
 249         const char* key
 250         const char* val
 251
 252 # TESTED
 253 size_t
 254 ZOOM_resultset_size(r)
 255         ZOOM_resultset r
 256
 257 # TESTED
 258 SV *
 259 ZOOM_resultset_records(r, start, count, return_records)
 260         ZOOM_resultset r
 261         size_t start
 262         size_t count
 263         int return_records
 264         CODE:
 265                 {
 266                 ZOOM_record *recs = 0;
 267                 if (return_records)
 268                         recs = (ZOOM_record*) xmalloc(count * sizeof *recs);
 269                 ZOOM_resultset_records(r, recs, start, count);
 270                 if (return_records) {
 271                         AV *av = newAV();
 272                         int i;
 273                         for (i = 0; i < count; i++) {
 274                                 SV *tmp = newSV(0);
 275                                 sv_setref_pv(tmp, "ZOOM_record", (void*) recs[i]);
 276                                 av_push(av, tmp);
 277                         }
 278                         RETVAL = newRV((SV*) av);
 279                 } else {
 280                         RETVAL = &PL_sv_undef;
 281                 }
 282                 }
 283         OUTPUT:
 284                 RETVAL
 285
 286 # TESTED
 287 ZOOM_record
 288 ZOOM_resultset_record(s, pos)
 289         ZOOM_resultset s
 290         size_t pos
 291
 292 # TESTED
 293 ZOOM_record
 294 ZOOM_resultset_record_immediate(s, pos)
 295         ZOOM_resultset s
 296         size_t pos
 297
 298 # TESTED
 299 void
 300 ZOOM_resultset_cache_reset(r)
 301         ZOOM_resultset r
 302
 303 # TESTED (but deprecated)
 304 void
 305 ZOOM_resultset_sort(r, sort_type, sort_spec)
 306         ZOOM_resultset r
 307         const char* sort_type
 308         const char* sort_spec
 309
 310 # TESTED
 311 int
 312 ZOOM_resultset_sort1(r, sort_type, sort_spec)
 313         ZOOM_resultset r
 314         const char* sort_type
 315         const char* sort_spec
 316
 317 # See "typemap" for discussion of the "const char *" return-type.
 318 #
 319 # TESTED
 320 ### but should use datachunk for in some (not all!) cases.
 321 const char *
 322 ZOOM_record_get(rec, type, len)
 323         ZOOM_record rec
 324         const char* type
 325         int &len
 326         OUTPUT:
 327                 RETVAL
 328                 len
 329
 330 # TESTED
 331 void
 332 ZOOM_record_destroy(rec)
 333         ZOOM_record rec
 334
 335 # TESTED
 336 ZOOM_record
 337 ZOOM_record_clone(srec)
 338         ZOOM_record srec
 339
 340 # TESTED
 341 ZOOM_query
 342 ZOOM_query_create()
 343
 344 # TESTED
 345 void
 346 ZOOM_query_destroy(s)
 347         ZOOM_query s
 348
 349 # TESTED
 350 int
 351 ZOOM_query_cql(s, str)
 352         ZOOM_query s
 353         const char* str
 354
 355 # TESTED
 356 int
 357 ZOOM_query_prefix(s, str)
 358         ZOOM_query s
 359         const char* str
 360
 361 # TESTED
 362 int
 363 ZOOM_query_sortby(s, criteria)
 364         ZOOM_query      s
 365         const char *    criteria
 366
 367 # TESTED
 368 ZOOM_scanset
 369 ZOOM_connection_scan(c, startterm)
 370         ZOOM_connection c
 371         const char* startterm
 372
 373 # TESTED
 374 const char *
 375 ZOOM_scanset_term(scan, pos, occ, len)
 376         ZOOM_scanset scan
 377         size_t pos
 378         int& occ
 379         int& len
 380         OUTPUT:
 381                 RETVAL
 382                 occ
 383                 len
 384
 385 # TESTED
 386 const char *
 387 ZOOM_scanset_display_term(scan, pos, occ, len)
 388         ZOOM_scanset scan
 389         size_t pos
 390         int& occ
 391         int& len
 392         OUTPUT:
 393                 RETVAL
 394                 occ
 395                 len
 396
 397 # TESTED
 398 size_t
 399 ZOOM_scanset_size(scan)
 400         ZOOM_scanset scan
 401
 402 # TESTED
 403 void
 404 ZOOM_scanset_destroy(scan)
 405         ZOOM_scanset scan
 406
 407 # TESTED
 408 const char *
 409 ZOOM_scanset_option_get(scan, key)
 410         ZOOM_scanset    scan
 411         const char *    key
 412
 413 # TESTED
 414 void
 415 ZOOM_scanset_option_set(scan, key, val)
 416         ZOOM_scanset    scan
 417         const char *    key
 418         const char *    val
 419
 420 # We ignore the return value of ZOOM_options_set_callback(), since it
 421 # is always just the address of the __ZOOM_option_callback() function.
 422 # The information that we actually want -- the address of the Perl
 423 # function in the callback_block -- is unavailable to us, as the
 424 # underlying C function doesn't give the block back.
 425 #
 426 # TESTED
 427 void
 428 ZOOM_options_set_callback(opt, function, handle)
 429         ZOOM_options opt
 430         SV* function;
 431         SV* handle;
 432         CODE:
 433                 {
 434                 /* The tiny amount of memory allocated here is never
 435                  * released, as options_destroy() doesn't do anything
 436                  * to the callback information.  Not a big deal.
 437                  * Also, I have no idea how to drive the Perl "mortal"
 438                  * reference-counting stuff, so I am just allocating
 439                  * copies which also never get released.  Don't sue!
 440                  */
 441                 struct callback_block *block = (struct callback_block*)
 442                         xmalloc(sizeof *block);
 443                 block->function = function;
 444                 block->handle = handle;
 445                 SvREFCNT(block->function);
 446                 SvREFCNT(block->handle);
 447                 ZOOM_options_set_callback(opt, __ZOOM_option_callback,
 448                                           (void*) block);
 449                 }
 450
 451 # TESTED
 452 ZOOM_options
 453 ZOOM_options_create()
 454
 455 # TESTED
 456 ZOOM_options
 457 ZOOM_options_create_with_parent(parent)
 458         ZOOM_options parent
 459
 460 # TESTED
 461 ZOOM_options
 462 ZOOM_options_create_with_parent2(parent1, parent2)
 463         ZOOM_options parent1
 464         ZOOM_options parent2
 465
 466 # TESTED
 467 const char *
 468 ZOOM_options_get(opt, name)
 469         ZOOM_options opt
 470         const char* name
 471
 472 # TESTED
 473 struct datachunk
 474 ZOOM_options_getl(opt, name, len)
 475         ZOOM_options opt
 476         const char* name
 477         int &len
 478         CODE:
 479                 RETVAL.data = (char*) ZOOM_options_getl(opt, name, &len);
 480                 RETVAL.len = len;
 481         OUTPUT:
 482                 RETVAL
 483                 len
 484
 485 # TESTED
 486 void
 487 ZOOM_options_set(opt, name, v)
 488         ZOOM_options opt
 489         const char* name
 490         const char* v
 491
 492 # TESTED
 493 void
 494 ZOOM_options_setl(opt, name, value, len)
 495         ZOOM_options opt
 496         const char* name
 497         opaquechar* value
 498         int len
 499
 500 # TESTED
 501 void
 502 ZOOM_options_destroy(opt)
 503         ZOOM_options opt
 504
 505 # TESTED
 506 int
 507 ZOOM_options_get_bool(opt, name, defa)
 508         ZOOM_options opt
 509         const char* name
 510         int defa
 511
 512 # TESTED
 513 int
 514 ZOOM_options_get_int(opt, name, defa)
 515         ZOOM_options opt
 516         const char* name
 517         int defa
 518
 519 # TESTED
 520 void
 521 ZOOM_options_set_int(opt, name, value)
 522         ZOOM_options opt
 523         const char* name
 524         int value
 525
 526 # TESTED
 527 ZOOM_package
 528 ZOOM_connection_package(c, options)
 529         ZOOM_connection c
 530         ZOOM_options    options
 531
 532 # TESTED
 533 void
 534 ZOOM_package_destroy(p)
 535         ZOOM_package    p
 536
 537 # TESTED
 538 void
 539 ZOOM_package_send(p, type)
 540         ZOOM_package    p
 541         const char *    type
 542
 543 # TESTED
 544 const char *
 545 ZOOM_package_option_get(p, key)
 546         ZOOM_package    p
 547         const char *    key
 548
 549 # TESTED
 550 void
 551 ZOOM_package_option_set(p, key, val)
 552         ZOOM_package    p
 553         const char *    key
 554         const char *    val
 555
 556 # UNTESTED
 557 int
 558 ZOOM_event(no, cs)
 559         int     no
 560         ZOOM_connection *       cs
 561
 562 # UNTESTED
 563 int
 564 ZOOM_connection_last_event(cs)
 565         ZOOM_connection cs
 566