ZOOM.xs

   1 /* $Id: ZOOM.xs,v 1.51 2008-05-14 13:31:39 mike Exp $ */
   2
   3 #include "EXTERN.h"
   4 #include "perl.h"
   5 #include "XSUB.h"
   6
   7 #include <yaz/zoom.h>
   8 #include <yaz/diagsrw.h>
   9 #include <yaz/xmalloc.h>
  10 #include <yaz/log.h>
  11 #include <yaz/yaz-version.h>
  12
  13 /* Used by the *_setl() functions */
  14 typedef char opaquechar;
  15
  16 /* Used as the return value of the *_getl() functions */
  17 struct datachunk {
  18         char *data;
  19         int len;
  20 };
  21
  22 /* Used to package Perl function-pointer and user-data together */
  23 struct callback_block {
  24         SV *function;
  25         SV *handle;
  26 };
  27
  28 /* The callback function used for ZOOM_options_set_callback().  I do
  29  * not claim to fully understand all the stack-hacking magic, and less
  30  * still the reference-counting/mortality stuff.  Accordingly, the
  31  * memory management here is best characterised as What I Could Get To
  32  * Work, More Or Less.
  33  */
  34 const char *__ZOOM_option_callback (void *handle, const char *name)
  35 {
  36         struct callback_block *cb = (struct callback_block*) handle;
  37         int count;
  38         SV *ret;
  39         char *s;
  40         char *res;
  41
  42         dSP;
  43
  44         ENTER;
  45         SAVETMPS;
  46
  47         PUSHMARK(SP);
  48         XPUSHs(cb->handle);
  49         XPUSHs(sv_2mortal(newSVpv(name, 0)));
  50         PUTBACK;
  51         /* Perl_sv_dump(0, cb->function); */
  52
  53         count = call_sv(cb->function, G_SCALAR);
  54
  55         SPAGAIN;
  56
  57         if (count != 1)
  58                 croak("callback function for ZOOM_options_get() returned %d values: should have returned exactly one", count);
  59
  60         ret = POPs;
  61         if (SvPOK(ret)) {
  62                 s = SvPV_nolen(ret);
  63                 /* ### `res' never gets freed!  I think it is
  64                  * impossible to solve this problem "correctly"
  65                  * because the ZOOM-C option callback interface is
  66                  * inadequate. */
  67                 res = xstrdup(s);
  68         } else {
  69                 res = 0;
  70         }
  71
  72         PUTBACK;
  73         FREETMPS;
  74         LEAVE;
  75
  76         return res;
  77 }
  78
  79
  80 MODULE = Net::Z3950::ZOOM               PACKAGE = Net::Z3950::ZOOM              PREFIX=ZOOM_
  81
  82 PROTOTYPES: ENABLE
  83
  84
  85 ZOOM_connection
  86 ZOOM_connection_new(host, portnum)
  87         const char* host
  88         int portnum
  89
  90 ZOOM_connection
  91 ZOOM_connection_create(options)
  92         ZOOM_options options
  93
  94 void
  95 ZOOM_connection_connect(c, host, portnum)
  96         ZOOM_connection c
  97         const char* host
  98         int portnum
  99
 100 void
 101 ZOOM_connection_destroy(c)
 102         ZOOM_connection c
 103
 104 const char *
 105 ZOOM_connection_option_get(c, key)
 106         ZOOM_connection c
 107         const char *key
 108
 109 struct datachunk
 110 ZOOM_connection_option_getl(c, key, len)
 111         ZOOM_connection c
 112         const char* key
 113         int &len
 114         CODE:
 115                 RETVAL.data = (char*) ZOOM_connection_option_getl(c, key, &len);
 116                 RETVAL.len = len;
 117         OUTPUT:
 118                 RETVAL
 119                 len
 120
 121 void
 122 ZOOM_connection_option_set(c, key, val)
 123         ZOOM_connection c
 124         const char *key
 125         const char *val
 126
 127 # In ZOOM-C, the `val' parameter is const char*.  However, our typemap
 128 # treats this as T_PV, i.e. it's "known" that it points to a
 129 # NUL-terminated string.  Instead, then, I here use opaquechar*, which
 130 # is an opaque pointer.  The underlying C function can then use this
 131 # along with `len' to Do The Right Thing.
 132 #
 133 void
 134 ZOOM_connection_option_setl(c, key, val, len)
 135         ZOOM_connection c
 136         const char* key
 137         opaquechar* val
 138         int len
 139
 140 # The reference parameters, `cp' and `addinfo', need to already have
 141 # values when this function is called, otherwise an "uninitialised
 142 # value" warning is generated.  As far as I can see, there is no way
 143 # around this: no way to specify in a prototype that an argument is
 144 # allowed to be undefined, for example.  Since these function will
 145 # never be called directly by well-behaved client code, but only by
 146 # our own wrapper classes, I think we can live with that.
 147 #
 148 # The poxing about with cpp and caddinfo is due to Perl XS's lack of
 149 # support for const char**, but who can blame it?  If you ask me, the
 150 # whole "const" thing was well-intentioned by ghastly mistake.
 151 #
 152 int
 153 ZOOM_connection_error(c, cp, addinfo)
 154         ZOOM_connection c
 155         char* &cp
 156         char* &addinfo
 157         CODE:
 158                 {
 159                 const char *ccp, *caddinfo;
 160                 RETVAL = ZOOM_connection_error(c, &ccp, &caddinfo);
 161                 cp = (char*) ccp;
 162                 addinfo = (char*) caddinfo;
 163                 }
 164         OUTPUT:
 165                 RETVAL
 166                 cp
 167                 addinfo
 168
 169 # See comments for ZOOM_connection_error() above
 170 int
 171 ZOOM_connection_error_x(c, cp, addinfo, diagset)
 172         ZOOM_connection c
 173         const char * &cp
 174         const char * &addinfo
 175         const char * &diagset
 176         CODE:
 177                 {
 178                 const char *ccp, *caddinfo, *cdset;
 179                 RETVAL = ZOOM_connection_error_x(c, &ccp, &caddinfo, &cdset);
 180                 cp = (char*) ccp;
 181                 addinfo = (char*) caddinfo;
 182                 diagset = (char*) cdset;
 183                 }
 184         OUTPUT:
 185                 RETVAL
 186                 cp
 187                 addinfo
 188                 diagset
 189
 190 int
 191 ZOOM_connection_errcode(c)
 192         ZOOM_connection c
 193
 194 const char *
 195 ZOOM_connection_errmsg(c)
 196         ZOOM_connection c
 197
 198 const char *
 199 ZOOM_connection_addinfo(c)
 200         ZOOM_connection c
 201
 202 const char *
 203 ZOOM_connection_diagset(c)
 204         ZOOM_connection c
 205
 206 const char *
 207 ZOOM_diag_str(error)
 208         int error
 209
 210 const char *
 211 ZOOM_diag_srw_str(error)
 212         int error
 213         CODE:
 214                 RETVAL = yaz_diag_srw_str(error);
 215         OUTPUT:
 216                 RETVAL
 217
 218 ZOOM_resultset
 219 ZOOM_connection_search(arg0, q)
 220         ZOOM_connection arg0
 221         ZOOM_query q
 222
 223 ZOOM_resultset
 224 ZOOM_connection_search_pqf(c, q)
 225         ZOOM_connection c
 226         const char *q
 227
 228 void
 229 ZOOM_resultset_destroy(r)
 230         ZOOM_resultset r
 231
 232 const char *
 233 ZOOM_resultset_option_get(r, key)
 234         ZOOM_resultset r
 235         const char* key
 236
 237 void
 238 ZOOM_resultset_option_set(r, key, val)
 239         ZOOM_resultset r
 240         const char* key
 241         const char* val
 242
 243 size_t
 244 ZOOM_resultset_size(r)
 245         ZOOM_resultset r
 246
 247 SV *
 248 ZOOM_resultset_records(r, start, count, return_records)
 249         ZOOM_resultset r
 250         size_t start
 251         size_t count
 252         int return_records
 253         CODE:
 254                 {
 255                 ZOOM_record *recs = 0;
 256                 if (return_records)
 257                         recs = (ZOOM_record*) xmalloc(count * sizeof *recs);
 258                 ZOOM_resultset_records(r, recs, start, count);
 259                 if (return_records) {
 260                         AV *av = newAV();
 261                         int i;
 262                         for (i = 0; i < count; i++) {
 263                                 SV *tmp = newSV(0);
 264                                 sv_setref_pv(tmp, "ZOOM_record", (void*) recs[i]);
 265                                 av_push(av, tmp);
 266                         }
 267                         RETVAL = newRV((SV*) av);
 268                 } else {
 269                         RETVAL = &PL_sv_undef;
 270                 }
 271                 }
 272         OUTPUT:
 273                 RETVAL
 274
 275 ZOOM_record
 276 ZOOM_resultset_record(s, pos)
 277         ZOOM_resultset s
 278         size_t pos
 279
 280 ZOOM_record
 281 ZOOM_resultset_record_immediate(s, pos)
 282         ZOOM_resultset s
 283         size_t pos
 284
 285 void
 286 ZOOM_resultset_cache_reset(r)
 287         ZOOM_resultset r
 288
 289 # TESTED (but deprecated)
 290 void
 291 ZOOM_resultset_sort(r, sort_type, sort_spec)
 292         ZOOM_resultset r
 293         const char* sort_type
 294         const char* sort_spec
 295
 296 int
 297 ZOOM_resultset_sort1(r, sort_type, sort_spec)
 298         ZOOM_resultset r
 299         const char* sort_type
 300         const char* sort_spec
 301
 302 # See comments for ZOOM_connection_error() above
 303 int
 304 ZOOM_record_error(rec, cp, addinfo, diagset)
 305         ZOOM_record rec
 306         const char* &cp
 307         const char* &addinfo
 308         const char* &diagset
 309         CODE:
 310                 {
 311                 const char *ccp = "", *caddinfo = "", *cdset = "";
 312                 RETVAL = ZOOM_record_error(rec, &ccp, &caddinfo, &cdset);
 313                 cp = (char*) ccp;
 314                 addinfo = (char*) caddinfo;
 315                 diagset = (char*) cdset;
 316                 }
 317         OUTPUT:
 318                 RETVAL
 319                 cp
 320                 addinfo
 321                 diagset
 322
 323 # See "typemap" for discussion of the "const char *" return-type.
 324 const char *
 325 ZOOM_record_get_string(rec, type)
 326         ZOOM_record rec
 327         const char* type
 328         INIT:
 329                 int len;
 330         CODE:
 331                 RETVAL = ZOOM_record_get(rec, type, &len);
 332         OUTPUT:
 333                 RETVAL
 334
 335 struct datachunk
 336 ZOOM_record_get_binary(rec, type)
 337         ZOOM_record rec
 338         const char* type
 339         CODE:
 340                 RETVAL.data = (char*) ZOOM_record_get(rec, type, &RETVAL.len);
 341         OUTPUT:
 342                 RETVAL
 343
 344 void
 345 ZOOM_record_destroy(rec)
 346         ZOOM_record rec
 347
 348 ZOOM_record
 349 ZOOM_record_clone(srec)
 350         ZOOM_record srec
 351
 352 ZOOM_query
 353 ZOOM_query_create()
 354
 355 void
 356 ZOOM_query_destroy(s)
 357         ZOOM_query s
 358
 359 int
 360 ZOOM_query_cql(s, str)
 361         ZOOM_query s
 362         const char* str
 363
 364 int
 365 ZOOM_query_cql2rpn(s, str, conn)
 366         ZOOM_query s
 367         const char* str
 368         ZOOM_connection conn
 369
 370 int
 371 ZOOM_query_ccl2rpn(s, query_str, config, errcode, errstr, errpos)
 372         ZOOM_query s
 373         const char* query_str
 374         const char* config
 375         int &errcode
 376         const char* &errstr
 377         int &errpos
 378         OUTPUT:
 379                 RETVAL
 380                 errcode
 381                 errstr
 382                 errpos
 383
 384 int
 385 ZOOM_query_prefix(s, str)
 386         ZOOM_query s
 387         const char* str
 388
 389 int
 390 ZOOM_query_sortby(s, criteria)
 391         ZOOM_query      s
 392         const char *    criteria
 393
 394 ZOOM_scanset
 395 ZOOM_connection_scan(c, startterm)
 396         ZOOM_connection c
 397         const char* startterm
 398
 399 ZOOM_scanset
 400 ZOOM_connection_scan1(c, startterm)
 401         ZOOM_connection c
 402         ZOOM_query startterm
 403
 404 const char *
 405 ZOOM_scanset_term(scan, pos, occ, len)
 406         ZOOM_scanset scan
 407         size_t pos
 408         int& occ
 409         int& len
 410         OUTPUT:
 411                 RETVAL
 412                 occ
 413                 len
 414
 415 const char *
 416 ZOOM_scanset_display_term(scan, pos, occ, len)
 417         ZOOM_scanset scan
 418         size_t pos
 419         int& occ
 420         int& len
 421         OUTPUT:
 422                 RETVAL
 423                 occ
 424                 len
 425
 426 size_t
 427 ZOOM_scanset_size(scan)
 428         ZOOM_scanset scan
 429
 430 void
 431 ZOOM_scanset_destroy(scan)
 432         ZOOM_scanset scan
 433
 434 const char *
 435 ZOOM_scanset_option_get(scan, key)
 436         ZOOM_scanset    scan
 437         const char *    key
 438
 439 void
 440 ZOOM_scanset_option_set(scan, key, val)
 441         ZOOM_scanset    scan
 442         const char *    key
 443         const char *    val
 444
 445 # We ignore the return value of ZOOM_options_set_callback(), since it
 446 # is always just the address of the __ZOOM_option_callback() function.
 447 # The information that we actually want -- the address of the Perl
 448 # function in the callback_block -- is unavailable to us, as the
 449 # underlying C function doesn't give the block back.
 450 #
 451 void
 452 ZOOM_options_set_callback(opt, function, handle)
 453         ZOOM_options opt
 454         SV* function;
 455         SV* handle;
 456         CODE:
 457                 {
 458                 /* The tiny amount of memory allocated here is never
 459                  * released, as options_destroy() doesn't do anything
 460                  * to the callback information.  Not a big deal.
 461                  * Also, I have no idea how to drive the Perl "mortal"
 462                  * reference-counting stuff, so I am just allocating
 463                  * copies which also never get released.  Don't sue!
 464                  */
 465                 struct callback_block *block = (struct callback_block*)
 466                         xmalloc(sizeof *block);
 467                 block->function = function;
 468                 block->handle = handle;
 469                 SvREFCNT(block->function);
 470                 SvREFCNT(block->handle);
 471                 ZOOM_options_set_callback(opt, __ZOOM_option_callback,
 472                                           (void*) block);
 473                 }
 474
 475 ZOOM_options
 476 ZOOM_options_create()
 477
 478 ZOOM_options
 479 ZOOM_options_create_with_parent(parent)
 480         ZOOM_options parent
 481
 482 ZOOM_options
 483 ZOOM_options_create_with_parent2(parent1, parent2)
 484         ZOOM_options parent1
 485         ZOOM_options parent2
 486
 487 const char *
 488 ZOOM_options_get(opt, name)
 489         ZOOM_options opt
 490         const char* name
 491
 492 struct datachunk
 493 ZOOM_options_getl(opt, name, len)
 494         ZOOM_options opt
 495         const char* name
 496         int &len
 497         CODE:
 498                 RETVAL.data = (char*) ZOOM_options_getl(opt, name, &len);
 499                 RETVAL.len = len;
 500         OUTPUT:
 501                 RETVAL
 502                 len
 503
 504 void
 505 ZOOM_options_set(opt, name, v)
 506         ZOOM_options opt
 507         const char* name
 508         const char* v
 509
 510 void
 511 ZOOM_options_setl(opt, name, value, len)
 512         ZOOM_options opt
 513         const char* name
 514         opaquechar* value
 515         int len
 516
 517 void
 518 ZOOM_options_destroy(opt)
 519         ZOOM_options opt
 520
 521 int
 522 ZOOM_options_get_bool(opt, name, defa)
 523         ZOOM_options opt
 524         const char* name
 525         int defa
 526
 527 int
 528 ZOOM_options_get_int(opt, name, defa)
 529         ZOOM_options opt
 530         const char* name
 531         int defa
 532
 533 void
 534 ZOOM_options_set_int(opt, name, value)
 535         ZOOM_options opt
 536         const char* name
 537         int value
 538
 539 ZOOM_package
 540 ZOOM_connection_package(c, options)
 541         ZOOM_connection c
 542         ZOOM_options    options
 543
 544 void
 545 ZOOM_package_destroy(p)
 546         ZOOM_package    p
 547
 548 void
 549 ZOOM_package_send(p, type)
 550         ZOOM_package    p
 551         const char *    type
 552
 553 const char *
 554 ZOOM_package_option_get(p, key)
 555         ZOOM_package    p
 556         const char *    key
 557
 558 void
 559 ZOOM_package_option_set(p, key, val)
 560         ZOOM_package    p
 561         const char *    key
 562         const char *    val
 563
 564 # This has to be called with a single argument which is a _reference_
 565 # to an array -- rather than directly with an array, which is of
 566 # course identical to passing arbitrarily many arguments.  This is
 567 # because there doesn't seem to be a way to do varargs in an XS
 568 # function.
 569 #
 570 int
 571 ZOOM_event(conns)
 572         SV* conns
 573         INIT:
 574                 SV *realconns;
 575                 I32 n, i;
 576                 ZOOM_connection *cs;
 577         CODE:
 578                 /*printf("* in ZOOM_event(%p)\n", conns);*/
 579                 if (!SvROK(conns)) {
 580                         /*printf("* argument is not a reference\n");*/
 581                         XSRETURN_IV(-1);
 582                 }
 583                 realconns = SvRV(conns);
 584                 /*printf("* realconns = %p\n", realconns);*/
 585                 if (SvTYPE(realconns) != SVt_PVAV) {
 586                         /*printf("* reference is not to an array\n");*/
 587                         XSRETURN_IV(-2);
 588                 }
 589                 n = av_len((AV*) realconns);
 590                 n++; /* The av_len() return-value is zero-based */
 591                 if (n == 0) {
 592                         /*printf("* No connections in referenced array\n");*/
 593                         XSRETURN_IV(-3);
 594                 }
 595
 596                 /*printf("* n = %d\n", n);*/
 597                 if ((cs = (ZOOM_connection*) malloc(n * sizeof *cs)) == 0) {
 598                         /*printf("* Too many connections (%d)\n", (int) n);*/
 599                         XSRETURN_IV(-4);
 600                 }
 601
 602                 for (i = 0; i < n; i++) {
 603                     SV **connp = av_fetch((AV*) realconns, i, (I32) 0);
 604                     SV *conn, *sv;
 605                     /*printf("* %d of %d: connp = %p\n", (int) i, (int) n,connp);*/
 606                     assert(connp != 0);
 607                     conn = *connp;
 608                     /*printf("* conn = %p\n", conn);*/
 609                     /*
 610                      * From here on, the tests and assertions seem to
 611                      * be ignored: if I pass in a reference to
 612                      * something other than a ZOOM_connection, or even
 613                      * if I pass a non-reference, the assertions still
 614                      * pass and everything seems to work until the
 615                      * segmentation fault bites.
 616                      */
 617                     assert(sv_derived_from(conn, "ZOOM_connection"));
 618                     /*printf("* passed assert(isa(ZOOM_connection))\n");*/
 619                     assert(SvROK(conn));
 620                     /*printf("* passed assert SvROK()\n");*/
 621                     sv = (SV*) SvRV(conn);
 622                     /*printf("* sv = %p\n", sv);*/
 623                     cs[i] = INT2PTR(ZOOM_connection, SvIV(sv));
 624                     /*printf("got cs[%d] of %d = %p\n", (int) i, (int) n, cs[i]);*/
 625                 }
 626                 RETVAL = ZOOM_event((int) n, cs);
 627                 free(cs);
 628         OUTPUT:
 629                 RETVAL
 630
 631 int
 632 ZOOM_connection_last_event(cs)
 633         ZOOM_connection cs
 634
 635 int
 636 ZOOM_connection_is_idle(cs)
 637         ZOOM_connection cs
 638
 639 int
 640 ZOOM_connection_peek_event(cs)
 641         ZOOM_connection cs
 642
 643
 644 # ----------------------------------------------------------------------------
 645 # What follows is the YAZ logging API.  This is not strictly part of
 646 # ZOOM, but it's so useful that it would be silly to omit.
 647
 648 int
 649 yaz_log_mask_str(str)
 650         const char *str
 651
 652 int
 653 yaz_log_module_level(name)
 654         const char *name
 655
 656 void
 657 yaz_log_init(level, prefix, name)
 658         int level
 659         const char *prefix
 660         const char *name
 661
 662 void
 663 yaz_log_init_file(fname)
 664         const char *fname
 665
 666 void
 667 yaz_log_init_level(level)
 668         int level
 669
 670 void
 671 yaz_log_init_prefix(prefix)
 672         const char *prefix
 673
 674 void
 675 yaz_log_time_format(fmt)
 676         const char *fmt
 677
 678 void
 679 yaz_log_init_max_size(mx)
 680         int mx
 681
 682 # <stdarg.h> interfaces are horrible to code for a Perl-C interface
 683 # layer.  Instead, we expect Perl applications to construct the
 684 # message themselves, and pass it in as an opaque lump.
 685 void
 686 yaz_log(level, str)
 687         int level
 688         const char *str
 689         CODE:
 690                 yaz_log(level, "%s", str);
 691
 692 # This is also not strictly part of ZOOM
 693 unsigned long
 694 yaz_version(version_str, sys_str)
 695         char *version_str
 696         char *sys_str
 697         OUTPUT:
 698                 RETVAL
 699                 version_str
 700                 sys_str
 701