← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/libpq-events.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/libpq-events.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>Event System</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="libpq - C Library"
 
16
HREF="libpq.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="Notice Processing"
 
19
HREF="libpq-notice-processing.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="Environment Variables"
 
22
HREF="libpq-envars.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="SECT1"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="Notice Processing"
 
57
HREF="libpq-notice-processing.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="libpq - C Library"
 
67
HREF="libpq.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
>Chapter 31. <SPAN
 
75
CLASS="APPLICATION"
 
76
>libpq</SPAN
 
77
> - C Library</TD
 
78
><TD
 
79
WIDTH="10%"
 
80
ALIGN="right"
 
81
VALIGN="top"
 
82
><A
 
83
TITLE="libpq - C Library"
 
84
HREF="libpq.html"
 
85
>Fast Forward</A
 
86
></TD
 
87
><TD
 
88
WIDTH="10%"
 
89
ALIGN="right"
 
90
VALIGN="top"
 
91
><A
 
92
TITLE="Environment Variables"
 
93
HREF="libpq-envars.html"
 
94
ACCESSKEY="N"
 
95
>Next</A
 
96
></TD
 
97
></TR
 
98
></TABLE
 
99
><HR
 
100
ALIGN="LEFT"
 
101
WIDTH="100%"></DIV
 
102
><DIV
 
103
CLASS="SECT1"
 
104
><H1
 
105
CLASS="SECT1"
 
106
><A
 
107
NAME="LIBPQ-EVENTS"
 
108
>31.12. Event System</A
 
109
></H1
 
110
><P
 
111
>   <SPAN
 
112
CLASS="APPLICATION"
 
113
>libpq</SPAN
 
114
>'s event system is designed to notify
 
115
   registered event handlers about interesting
 
116
   <SPAN
 
117
CLASS="APPLICATION"
 
118
>libpq</SPAN
 
119
> events, such as the creation or
 
120
   destruction of <TT
 
121
CLASS="STRUCTNAME"
 
122
>PGconn</TT
 
123
> and
 
124
   <TT
 
125
CLASS="STRUCTNAME"
 
126
>PGresult</TT
 
127
> objects.  A principal use case is that
 
128
   this allows applications to associate their own data with a
 
129
   <TT
 
130
CLASS="STRUCTNAME"
 
131
>PGconn</TT
 
132
> or <TT
 
133
CLASS="STRUCTNAME"
 
134
>PGresult</TT
 
135
>
 
136
   and ensure that that data is freed at an appropriate time.
 
137
  </P
 
138
><P
 
139
>   Each registered event handler is associated with two pieces of data,
 
140
   known to <SPAN
 
141
CLASS="APPLICATION"
 
142
>libpq</SPAN
 
143
> only as opaque <TT
 
144
CLASS="LITERAL"
 
145
>void *</TT
 
146
>
 
147
   pointers.  There is a <I
 
148
CLASS="FIRSTTERM"
 
149
>passthrough</I
 
150
> pointer that is provided
 
151
   by the application when the event handler is registered with a
 
152
   <TT
 
153
CLASS="STRUCTNAME"
 
154
>PGconn</TT
 
155
>.  The passthrough pointer never changes for the
 
156
   life of the <TT
 
157
CLASS="STRUCTNAME"
 
158
>PGconn</TT
 
159
> and all <TT
 
160
CLASS="STRUCTNAME"
 
161
>PGresult</TT
 
162
>s
 
163
   generated from it; so if used, it must point to long-lived data.
 
164
   In addition there is an <I
 
165
CLASS="FIRSTTERM"
 
166
>instance data</I
 
167
> pointer, which starts
 
168
   out <TT
 
169
CLASS="SYMBOL"
 
170
>NULL</TT
 
171
> in every <TT
 
172
CLASS="STRUCTNAME"
 
173
>PGconn</TT
 
174
> and <TT
 
175
CLASS="STRUCTNAME"
 
176
>PGresult</TT
 
177
>.
 
178
   This pointer can be manipulated using the
 
179
   <CODE
 
180
CLASS="FUNCTION"
 
181
>PQinstanceData</CODE
 
182
>,
 
183
   <CODE
 
184
CLASS="FUNCTION"
 
185
>PQsetInstanceData</CODE
 
186
>,
 
187
   <CODE
 
188
CLASS="FUNCTION"
 
189
>PQresultInstanceData</CODE
 
190
> and
 
191
   <CODE
 
192
CLASS="FUNCTION"
 
193
>PQsetResultInstanceData</CODE
 
194
> functions.  Note that
 
195
   unlike the passthrough pointer, instance data of a <TT
 
196
CLASS="STRUCTNAME"
 
197
>PGconn</TT
 
198
>
 
199
   is not automatically inherited by <TT
 
200
CLASS="STRUCTNAME"
 
201
>PGresult</TT
 
202
>s created from
 
203
   it.  <SPAN
 
204
CLASS="APPLICATION"
 
205
>libpq</SPAN
 
206
> does not know what passthrough
 
207
   and instance data pointers point to (if anything) and will never attempt
 
208
   to free them &mdash; that is the responsibility of the event handler.
 
209
  </P
 
210
><DIV
 
211
CLASS="SECT2"
 
212
><H2
 
213
CLASS="SECT2"
 
214
><A
 
215
NAME="LIBPQ-EVENTS-TYPES"
 
216
>31.12.1. Event Types</A
 
217
></H2
 
218
><P
 
219
>    The enum <TT
 
220
CLASS="LITERAL"
 
221
>PGEventId</TT
 
222
> names the types of events handled by
 
223
    the event system.  All its values have names beginning with
 
224
    <TT
 
225
CLASS="LITERAL"
 
226
>PGEVT</TT
 
227
>.  For each event type, there is a corresponding
 
228
    event info structure that carries the parameters passed to the event
 
229
    handlers.  The event types are:
 
230
   </P
 
231
><P
 
232
></P
 
233
><DIV
 
234
CLASS="VARIABLELIST"
 
235
><DL
 
236
><DT
 
237
><A
 
238
NAME="LIBPQ-PGEVT-REGISTER"
 
239
></A
 
240
><TT
 
241
CLASS="LITERAL"
 
242
>PGEVT_REGISTER</TT
 
243
></DT
 
244
><DD
 
245
><P
 
246
>       The register event occurs when <CODE
 
247
CLASS="FUNCTION"
 
248
>PQregisterEventProc</CODE
 
249
>
 
250
       is called.  It is the ideal time to initialize any
 
251
       <TT
 
252
CLASS="LITERAL"
 
253
>instanceData</TT
 
254
> an event procedure may need.  Only one
 
255
       register event will be fired per event handler per connection.  If the
 
256
       event procedure fails, the registration is aborted.
 
257
 
 
258
</P><PRE
 
259
CLASS="SYNOPSIS"
 
260
>typedef struct
 
261
{
 
262
    PGconn *conn;
 
263
} PGEventRegister;</PRE
 
264
><P>
 
265
 
 
266
       When a <TT
 
267
CLASS="LITERAL"
 
268
>PGEVT_REGISTER</TT
 
269
> event is received, the
 
270
       <TT
 
271
CLASS="PARAMETER"
 
272
>evtInfo</TT
 
273
> pointer should be cast to a
 
274
       <TT
 
275
CLASS="STRUCTNAME"
 
276
>PGEventRegister *</TT
 
277
>.  This structure contains a
 
278
       <TT
 
279
CLASS="STRUCTNAME"
 
280
>PGconn</TT
 
281
> that should be in the
 
282
       <TT
 
283
CLASS="LITERAL"
 
284
>CONNECTION_OK</TT
 
285
> status; guaranteed if one calls
 
286
       <CODE
 
287
CLASS="FUNCTION"
 
288
>PQregisterEventProc</CODE
 
289
> right after obtaining a good
 
290
       <TT
 
291
CLASS="STRUCTNAME"
 
292
>PGconn</TT
 
293
>.  When returning a failure code, all
 
294
       cleanup must be performed as no <TT
 
295
CLASS="LITERAL"
 
296
>PGEVT_CONNDESTROY</TT
 
297
>
 
298
       event will be sent.
 
299
      </P
 
300
></DD
 
301
><DT
 
302
><A
 
303
NAME="LIBPQ-PGEVT-CONNRESET"
 
304
></A
 
305
><TT
 
306
CLASS="LITERAL"
 
307
>PGEVT_CONNRESET</TT
 
308
></DT
 
309
><DD
 
310
><P
 
311
>       The connection reset event is fired on completion of
 
312
       <CODE
 
313
CLASS="FUNCTION"
 
314
>PQreset</CODE
 
315
> or <CODE
 
316
CLASS="FUNCTION"
 
317
>PQresetPoll</CODE
 
318
>.  In
 
319
       both cases, the event is only fired if the reset was successful.  If
 
320
       the event procedure fails, the entire connection reset will fail; the
 
321
       <TT
 
322
CLASS="STRUCTNAME"
 
323
>PGconn</TT
 
324
> is put into
 
325
       <TT
 
326
CLASS="LITERAL"
 
327
>CONNECTION_BAD</TT
 
328
> status and
 
329
       <CODE
 
330
CLASS="FUNCTION"
 
331
>PQresetPoll</CODE
 
332
> will return
 
333
       <TT
 
334
CLASS="LITERAL"
 
335
>PGRES_POLLING_FAILED</TT
 
336
>.
 
337
 
 
338
</P><PRE
 
339
CLASS="SYNOPSIS"
 
340
>typedef struct
 
341
{
 
342
    PGconn *conn;
 
343
} PGEventConnReset;</PRE
 
344
><P>
 
345
 
 
346
       When a <TT
 
347
CLASS="LITERAL"
 
348
>PGEVT_CONNRESET</TT
 
349
> event is received, the
 
350
       <TT
 
351
CLASS="PARAMETER"
 
352
>evtInfo</TT
 
353
> pointer should be cast to a
 
354
       <TT
 
355
CLASS="STRUCTNAME"
 
356
>PGEventConnReset *</TT
 
357
>.  Although the contained
 
358
       <TT
 
359
CLASS="STRUCTNAME"
 
360
>PGconn</TT
 
361
> was just reset, all event data remains
 
362
       unchanged.  This event should be used to reset/reload/requery any
 
363
       associated <TT
 
364
CLASS="LITERAL"
 
365
>instanceData</TT
 
366
>.  Note that even if the
 
367
       event procedure fails to process <TT
 
368
CLASS="LITERAL"
 
369
>PGEVT_CONNRESET</TT
 
370
>, it will
 
371
       still receive a <TT
 
372
CLASS="LITERAL"
 
373
>PGEVT_CONNDESTROY</TT
 
374
> event when the connection
 
375
       is closed.
 
376
      </P
 
377
></DD
 
378
><DT
 
379
><A
 
380
NAME="LIBPQ-PGEVT-CONNDESTROY"
 
381
></A
 
382
><TT
 
383
CLASS="LITERAL"
 
384
>PGEVT_CONNDESTROY</TT
 
385
></DT
 
386
><DD
 
387
><P
 
388
>       The connection destroy event is fired in response to
 
389
       <CODE
 
390
CLASS="FUNCTION"
 
391
>PQfinish</CODE
 
392
>.  It is the event procedure's
 
393
       responsibility to properly clean up its event data as libpq has no
 
394
       ability to manage this memory.  Failure to clean up will lead
 
395
       to memory leaks.
 
396
 
 
397
</P><PRE
 
398
CLASS="SYNOPSIS"
 
399
>typedef struct
 
400
{
 
401
    PGconn *conn;
 
402
} PGEventConnDestroy;</PRE
 
403
><P>
 
404
 
 
405
       When a <TT
 
406
CLASS="LITERAL"
 
407
>PGEVT_CONNDESTROY</TT
 
408
> event is received, the
 
409
       <TT
 
410
CLASS="PARAMETER"
 
411
>evtInfo</TT
 
412
> pointer should be cast to a
 
413
       <TT
 
414
CLASS="STRUCTNAME"
 
415
>PGEventConnDestroy *</TT
 
416
>.  This event is fired
 
417
       prior to <CODE
 
418
CLASS="FUNCTION"
 
419
>PQfinish</CODE
 
420
> performing any other cleanup.
 
421
       The return value of the event procedure is ignored since there is no
 
422
       way of indicating a failure from <CODE
 
423
CLASS="FUNCTION"
 
424
>PQfinish</CODE
 
425
>.  Also,
 
426
       an event procedure failure should not abort the process of cleaning up
 
427
       unwanted memory.
 
428
      </P
 
429
></DD
 
430
><DT
 
431
><A
 
432
NAME="LIBPQ-PGEVT-RESULTCREATE"
 
433
></A
 
434
><TT
 
435
CLASS="LITERAL"
 
436
>PGEVT_RESULTCREATE</TT
 
437
></DT
 
438
><DD
 
439
><P
 
440
>       The result creation event is fired in response to any query execution
 
441
       function that generates a result, including
 
442
       <CODE
 
443
CLASS="FUNCTION"
 
444
>PQgetResult</CODE
 
445
>.  This event will only be fired after
 
446
       the result has been created successfully.
 
447
 
 
448
</P><PRE
 
449
CLASS="SYNOPSIS"
 
450
>typedef struct
 
451
{
 
452
    PGconn *conn;
 
453
    PGresult *result;
 
454
} PGEventResultCreate;</PRE
 
455
><P>
 
456
 
 
457
       When a <TT
 
458
CLASS="LITERAL"
 
459
>PGEVT_RESULTCREATE</TT
 
460
> event is received, the
 
461
       <TT
 
462
CLASS="PARAMETER"
 
463
>evtInfo</TT
 
464
> pointer should be cast to a
 
465
       <TT
 
466
CLASS="STRUCTNAME"
 
467
>PGEventResultCreate *</TT
 
468
>.  The
 
469
       <TT
 
470
CLASS="PARAMETER"
 
471
>conn</TT
 
472
> is the connection used to generate the
 
473
       result.  This is the ideal place to initialize any
 
474
       <TT
 
475
CLASS="LITERAL"
 
476
>instanceData</TT
 
477
> that needs to be associated with the
 
478
       result.  If the event procedure fails, the result will be cleared and
 
479
       the failure will be propagated.  The event procedure must not try to
 
480
       <CODE
 
481
CLASS="FUNCTION"
 
482
>PQclear</CODE
 
483
> the result object for itself.  When returning a
 
484
       failure code, all cleanup must be performed as no
 
485
       <TT
 
486
CLASS="LITERAL"
 
487
>PGEVT_RESULTDESTROY</TT
 
488
> event will be sent.
 
489
      </P
 
490
></DD
 
491
><DT
 
492
><A
 
493
NAME="LIBPQ-PGEVT-RESULTCOPY"
 
494
></A
 
495
><TT
 
496
CLASS="LITERAL"
 
497
>PGEVT_RESULTCOPY</TT
 
498
></DT
 
499
><DD
 
500
><P
 
501
>       The result copy event is fired in response to
 
502
       <CODE
 
503
CLASS="FUNCTION"
 
504
>PQcopyResult</CODE
 
505
>.  This event will only be fired after
 
506
       the copy is complete.  Only event procedures that have
 
507
       successfully handled the <TT
 
508
CLASS="LITERAL"
 
509
>PGEVT_RESULTCREATE</TT
 
510
>
 
511
       or <TT
 
512
CLASS="LITERAL"
 
513
>PGEVT_RESULTCOPY</TT
 
514
> event for the source result
 
515
       will receive <TT
 
516
CLASS="LITERAL"
 
517
>PGEVT_RESULTCOPY</TT
 
518
> events.
 
519
 
 
520
</P><PRE
 
521
CLASS="SYNOPSIS"
 
522
>typedef struct
 
523
{
 
524
    const PGresult *src;
 
525
    PGresult *dest;
 
526
} PGEventResultCopy;</PRE
 
527
><P>
 
528
 
 
529
       When a <TT
 
530
CLASS="LITERAL"
 
531
>PGEVT_RESULTCOPY</TT
 
532
> event is received, the
 
533
       <TT
 
534
CLASS="PARAMETER"
 
535
>evtInfo</TT
 
536
> pointer should be cast to a
 
537
       <TT
 
538
CLASS="STRUCTNAME"
 
539
>PGEventResultCopy *</TT
 
540
>.  The
 
541
       <TT
 
542
CLASS="PARAMETER"
 
543
>src</TT
 
544
> result is what was copied while the
 
545
       <TT
 
546
CLASS="PARAMETER"
 
547
>dest</TT
 
548
> result is the copy destination.  This event
 
549
       can be used to provide a deep copy of <TT
 
550
CLASS="LITERAL"
 
551
>instanceData</TT
 
552
>,
 
553
       since <TT
 
554
CLASS="LITERAL"
 
555
>PQcopyResult</TT
 
556
> cannot do that.  If the event
 
557
       procedure fails, the entire copy operation will fail and the
 
558
       <TT
 
559
CLASS="PARAMETER"
 
560
>dest</TT
 
561
> result will be cleared.   When returning a
 
562
       failure code, all cleanup must be performed as no
 
563
       <TT
 
564
CLASS="LITERAL"
 
565
>PGEVT_RESULTDESTROY</TT
 
566
> event will be sent for the
 
567
       destination result.
 
568
      </P
 
569
></DD
 
570
><DT
 
571
><A
 
572
NAME="LIBPQ-PGEVT-RESULTDESTROY"
 
573
></A
 
574
><TT
 
575
CLASS="LITERAL"
 
576
>PGEVT_RESULTDESTROY</TT
 
577
></DT
 
578
><DD
 
579
><P
 
580
>       The result destroy event is fired in response to a
 
581
       <CODE
 
582
CLASS="FUNCTION"
 
583
>PQclear</CODE
 
584
>.  It is the event procedure's
 
585
       responsibility to properly clean up its event data as libpq has no
 
586
       ability to manage this memory.  Failure to clean up will lead
 
587
       to memory leaks.
 
588
 
 
589
</P><PRE
 
590
CLASS="SYNOPSIS"
 
591
>typedef struct
 
592
{
 
593
    PGresult *result;
 
594
} PGEventResultDestroy;</PRE
 
595
><P>
 
596
 
 
597
       When a <TT
 
598
CLASS="LITERAL"
 
599
>PGEVT_RESULTDESTROY</TT
 
600
> event is received, the
 
601
       <TT
 
602
CLASS="PARAMETER"
 
603
>evtInfo</TT
 
604
> pointer should be cast to a
 
605
       <TT
 
606
CLASS="STRUCTNAME"
 
607
>PGEventResultDestroy *</TT
 
608
>.  This event is fired
 
609
       prior to <CODE
 
610
CLASS="FUNCTION"
 
611
>PQclear</CODE
 
612
> performing any other cleanup.
 
613
       The return value of the event procedure is ignored since there is no
 
614
       way of indicating a failure from <CODE
 
615
CLASS="FUNCTION"
 
616
>PQclear</CODE
 
617
>.  Also,
 
618
       an event procedure failure should not abort the process of cleaning up
 
619
       unwanted memory.
 
620
      </P
 
621
></DD
 
622
></DL
 
623
></DIV
 
624
></DIV
 
625
><DIV
 
626
CLASS="SECT2"
 
627
><H2
 
628
CLASS="SECT2"
 
629
><A
 
630
NAME="LIBPQ-EVENTS-PROC"
 
631
>31.12.2. Event Callback Procedure</A
 
632
></H2
 
633
><P
 
634
></P
 
635
><DIV
 
636
CLASS="VARIABLELIST"
 
637
><DL
 
638
><DT
 
639
><A
 
640
NAME="LIBPQ-PGEVENTPROC"
 
641
></A
 
642
><TT
 
643
CLASS="LITERAL"
 
644
>PGEventProc</TT
 
645
>
 
646
      </DT
 
647
><DD
 
648
><P
 
649
>       <TT
 
650
CLASS="LITERAL"
 
651
>PGEventProc</TT
 
652
> is a typedef for a pointer to an
 
653
       event procedure, that is, the user callback function that receives
 
654
       events from libpq.  The signature of an event procedure must be
 
655
 
 
656
</P><PRE
 
657
CLASS="SYNOPSIS"
 
658
>int eventproc(PGEventId evtId, void *evtInfo, void *passThrough)</PRE
 
659
><P>
 
660
 
 
661
       The <TT
 
662
CLASS="PARAMETER"
 
663
>evtId</TT
 
664
> parameter indicates which
 
665
       <TT
 
666
CLASS="LITERAL"
 
667
>PGEVT</TT
 
668
> event occurred.  The
 
669
       <TT
 
670
CLASS="PARAMETER"
 
671
>evtInfo</TT
 
672
> pointer must be cast to the appropriate
 
673
       structure type to obtain further information about the event.
 
674
       The <TT
 
675
CLASS="PARAMETER"
 
676
>passThrough</TT
 
677
> parameter is the pointer
 
678
       provided to <CODE
 
679
CLASS="FUNCTION"
 
680
>PQregisterEventProc</CODE
 
681
> when the event
 
682
       procedure was registered.  The function should return a non-zero value
 
683
       if it succeeds and zero if it fails.
 
684
      </P
 
685
><P
 
686
>       A particular event procedure can be registered only once in any
 
687
       <TT
 
688
CLASS="STRUCTNAME"
 
689
>PGconn</TT
 
690
>.  This is because the address of the procedure
 
691
       is used as a lookup key to identify the associated instance data.
 
692
      </P
 
693
><DIV
 
694
CLASS="CAUTION"
 
695
><P
 
696
></P
 
697
><TABLE
 
698
CLASS="CAUTION"
 
699
BORDER="1"
 
700
WIDTH="90%"
 
701
><TR
 
702
><TD
 
703
ALIGN="CENTER"
 
704
><B
 
705
>Caution</B
 
706
></TD
 
707
></TR
 
708
><TR
 
709
><TD
 
710
ALIGN="LEFT"
 
711
><P
 
712
>        On Windows, functions can have two different addresses: one visible
 
713
        from outside a DLL and another visible from inside the DLL.  One
 
714
        should be careful that only one of these addresses is used with
 
715
        <SPAN
 
716
CLASS="APPLICATION"
 
717
>libpq</SPAN
 
718
>'s event-procedure functions, else confusion will
 
719
        result.  The simplest rule for writing code that will work is to
 
720
        ensure that event procedures are declared <TT
 
721
CLASS="LITERAL"
 
722
>static</TT
 
723
>.  If the
 
724
        procedure's address must be available outside its own source file,
 
725
        expose a separate function to return the address.
 
726
       </P
 
727
></TD
 
728
></TR
 
729
></TABLE
 
730
></DIV
 
731
></DD
 
732
></DL
 
733
></DIV
 
734
></DIV
 
735
><DIV
 
736
CLASS="SECT2"
 
737
><H2
 
738
CLASS="SECT2"
 
739
><A
 
740
NAME="LIBPQ-EVENTS-FUNCS"
 
741
>31.12.3. Event Support Functions</A
 
742
></H2
 
743
><P
 
744
></P
 
745
><DIV
 
746
CLASS="VARIABLELIST"
 
747
><DL
 
748
><DT
 
749
><A
 
750
NAME="LIBPQ-PQREGISTEREVENTPROC"
 
751
></A
 
752
><CODE
 
753
CLASS="FUNCTION"
 
754
>PQregisterEventProc</CODE
 
755
>
 
756
      </DT
 
757
><DD
 
758
><P
 
759
>       Registers an event callback procedure with libpq.
 
760
 
 
761
</P><PRE
 
762
CLASS="SYNOPSIS"
 
763
>int PQregisterEventProc(PGconn *conn, PGEventProc proc,
 
764
                        const char *name, void *passThrough);</PRE
 
765
><P>
 
766
      </P
 
767
><P
 
768
>       An event procedure must be registered once on each
 
769
       <TT
 
770
CLASS="STRUCTNAME"
 
771
>PGconn</TT
 
772
> you want to receive events about.  There is no
 
773
       limit, other than memory, on the number of event procedures that
 
774
       can be registered with a connection.  The function returns a non-zero
 
775
       value if it succeeds and zero if it fails.
 
776
      </P
 
777
><P
 
778
>       The <TT
 
779
CLASS="PARAMETER"
 
780
>proc</TT
 
781
> argument will be called when a libpq
 
782
       event is fired.  Its memory address is also used to lookup
 
783
       <TT
 
784
CLASS="LITERAL"
 
785
>instanceData</TT
 
786
>.  The <TT
 
787
CLASS="PARAMETER"
 
788
>name</TT
 
789
>
 
790
       argument is used to refer to the event procedure in error messages.
 
791
       This value cannot be <TT
 
792
CLASS="SYMBOL"
 
793
>NULL</TT
 
794
> or a zero-length string.  The name string is
 
795
       copied into the <TT
 
796
CLASS="STRUCTNAME"
 
797
>PGconn</TT
 
798
>, so what is passed need not be
 
799
       long-lived.  The <TT
 
800
CLASS="PARAMETER"
 
801
>passThrough</TT
 
802
> pointer is passed
 
803
       to the <TT
 
804
CLASS="PARAMETER"
 
805
>proc</TT
 
806
> whenever an event occurs. This
 
807
       argument can be <TT
 
808
CLASS="SYMBOL"
 
809
>NULL</TT
 
810
>.
 
811
      </P
 
812
></DD
 
813
><DT
 
814
><A
 
815
NAME="LIBPQ-PQSETINSTANCEDATA"
 
816
></A
 
817
><CODE
 
818
CLASS="FUNCTION"
 
819
>PQsetInstanceData</CODE
 
820
>
 
821
      </DT
 
822
><DD
 
823
><P
 
824
>       Sets the connection <TT
 
825
CLASS="PARAMETER"
 
826
>conn</TT
 
827
>'s <TT
 
828
CLASS="LITERAL"
 
829
>instanceData</TT
 
830
>
 
831
       for procedure <TT
 
832
CLASS="PARAMETER"
 
833
>proc</TT
 
834
> to <TT
 
835
CLASS="PARAMETER"
 
836
>data</TT
 
837
>.  This
 
838
       returns non-zero for success and zero for failure.  (Failure is
 
839
       only possible if <TT
 
840
CLASS="PARAMETER"
 
841
>proc</TT
 
842
> has not been properly
 
843
       registered in <TT
 
844
CLASS="PARAMETER"
 
845
>conn</TT
 
846
>.)
 
847
 
 
848
</P><PRE
 
849
CLASS="SYNOPSIS"
 
850
>int PQsetInstanceData(PGconn *conn, PGEventProc proc, void *data);</PRE
 
851
><P>
 
852
      </P
 
853
></DD
 
854
><DT
 
855
><A
 
856
NAME="LIBPQ-PQINSTANCEDATA"
 
857
></A
 
858
><CODE
 
859
CLASS="FUNCTION"
 
860
>PQinstanceData</CODE
 
861
>
 
862
      </DT
 
863
><DD
 
864
><P
 
865
>       Returns the
 
866
       connection <TT
 
867
CLASS="PARAMETER"
 
868
>conn</TT
 
869
>'s <TT
 
870
CLASS="LITERAL"
 
871
>instanceData</TT
 
872
>
 
873
       associated with procedure <TT
 
874
CLASS="PARAMETER"
 
875
>proc</TT
 
876
>,
 
877
       or <TT
 
878
CLASS="SYMBOL"
 
879
>NULL</TT
 
880
> if there is none.
 
881
 
 
882
</P><PRE
 
883
CLASS="SYNOPSIS"
 
884
>void *PQinstanceData(const PGconn *conn, PGEventProc proc);</PRE
 
885
><P>
 
886
      </P
 
887
></DD
 
888
><DT
 
889
><A
 
890
NAME="LIBPQ-PQRESULTSETINSTANCEDATA"
 
891
></A
 
892
><CODE
 
893
CLASS="FUNCTION"
 
894
>PQresultSetInstanceData</CODE
 
895
>
 
896
      </DT
 
897
><DD
 
898
><P
 
899
>       Sets the result's <TT
 
900
CLASS="LITERAL"
 
901
>instanceData</TT
 
902
>
 
903
       for <TT
 
904
CLASS="PARAMETER"
 
905
>proc</TT
 
906
> to <TT
 
907
CLASS="PARAMETER"
 
908
>data</TT
 
909
>.  This returns
 
910
       non-zero for success and zero for failure.  (Failure is only
 
911
       possible if <TT
 
912
CLASS="PARAMETER"
 
913
>proc</TT
 
914
> has not been properly registered
 
915
       in the result.)
 
916
 
 
917
</P><PRE
 
918
CLASS="SYNOPSIS"
 
919
>int PQresultSetInstanceData(PGresult *res, PGEventProc proc, void *data);</PRE
 
920
><P>
 
921
      </P
 
922
></DD
 
923
><DT
 
924
><A
 
925
NAME="LIBPQ-PQRESULTINSTANCEDATA"
 
926
></A
 
927
><CODE
 
928
CLASS="FUNCTION"
 
929
>PQresultInstanceData</CODE
 
930
>
 
931
      </DT
 
932
><DD
 
933
><P
 
934
>       Returns the result's <TT
 
935
CLASS="LITERAL"
 
936
>instanceData</TT
 
937
> associated with <TT
 
938
CLASS="PARAMETER"
 
939
>proc</TT
 
940
>, or <TT
 
941
CLASS="SYMBOL"
 
942
>NULL</TT
 
943
>
 
944
       if there is none.
 
945
 
 
946
</P><PRE
 
947
CLASS="SYNOPSIS"
 
948
>void *PQresultInstanceData(const PGresult *res, PGEventProc proc);</PRE
 
949
><P>
 
950
      </P
 
951
></DD
 
952
></DL
 
953
></DIV
 
954
></DIV
 
955
><DIV
 
956
CLASS="SECT2"
 
957
><H2
 
958
CLASS="SECT2"
 
959
><A
 
960
NAME="LIBPQ-EVENTS-EXAMPLE"
 
961
>31.12.4. Event Example</A
 
962
></H2
 
963
><P
 
964
>    Here is a skeleton example of managing private data associated with
 
965
    libpq connections and results.
 
966
   </P
 
967
><PRE
 
968
CLASS="PROGRAMLISTING"
 
969
>/* required header for libpq events (note: includes libpq-fe.h) */
 
970
#include &#60;libpq-events.h&#62;
 
971
 
 
972
/* The instanceData */
 
973
typedef struct
 
974
{
 
975
    int n;
 
976
    char *str;
 
977
} mydata;
 
978
 
 
979
/* PGEventProc */
 
980
static int myEventProc(PGEventId evtId, void *evtInfo, void *passThrough);
 
981
 
 
982
int
 
983
main(void)
 
984
{
 
985
    mydata *data;
 
986
    PGresult *res;
 
987
    PGconn *conn = PQconnectdb("dbname = postgres");
 
988
 
 
989
    if (PQstatus(conn) != CONNECTION_OK)
 
990
    {
 
991
        fprintf(stderr, "Connection to database failed: %s",
 
992
                PQerrorMessage(conn));
 
993
        PQfinish(conn);
 
994
        return 1;
 
995
    }
 
996
 
 
997
    /* called once on any connection that should receive events.
 
998
     * Sends a PGEVT_REGISTER to myEventProc.
 
999
     */
 
1000
    if (!PQregisterEventProc(conn, myEventProc, "mydata_proc", NULL))
 
1001
    {
 
1002
        fprintf(stderr, "Cannot register PGEventProc\n");
 
1003
        PQfinish(conn);
 
1004
        return 1;
 
1005
    }
 
1006
 
 
1007
    /* conn instanceData is available */
 
1008
    data = PQinstanceData(conn, myEventProc);
 
1009
 
 
1010
    /* Sends a PGEVT_RESULTCREATE to myEventProc */
 
1011
    res = PQexec(conn, "SELECT 1 + 1");
 
1012
 
 
1013
    /* result instanceData is available */
 
1014
    data = PQresultInstanceData(res, myEventProc);
 
1015
 
 
1016
    /* If PG_COPYRES_EVENTS is used, sends a PGEVT_RESULTCOPY to myEventProc */
 
1017
    res_copy = PQcopyResult(res, PG_COPYRES_TUPLES | PG_COPYRES_EVENTS);
 
1018
 
 
1019
    /* result instanceData is available if PG_COPYRES_EVENTS was
 
1020
     * used during the PQcopyResult call.
 
1021
     */
 
1022
    data = PQresultInstanceData(res_copy, myEventProc);
 
1023
 
 
1024
    /* Both clears send a PGEVT_RESULTDESTROY to myEventProc */
 
1025
    PQclear(res);
 
1026
    PQclear(res_copy);
 
1027
 
 
1028
    /* Sends a PGEVT_CONNDESTROY to myEventProc */
 
1029
    PQfinish(conn);
 
1030
 
 
1031
    return 0;
 
1032
}
 
1033
 
 
1034
static int
 
1035
myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
 
1036
{
 
1037
    switch (evtId)
 
1038
    {
 
1039
        case PGEVT_REGISTER:
 
1040
        {
 
1041
            PGEventRegister *e = (PGEventRegister *)evtInfo;
 
1042
            mydata *data = get_mydata(e-&#62;conn);
 
1043
 
 
1044
            /* associate app specific data with connection */
 
1045
            PQsetInstanceData(e-&#62;conn, myEventProc, data);
 
1046
            break;
 
1047
        }
 
1048
 
 
1049
        case PGEVT_CONNRESET:
 
1050
        {
 
1051
            PGEventConnReset *e = (PGEventConnReset *)evtInfo;
 
1052
            mydata *data = PQinstanceData(e-&#62;conn, myEventProc);
 
1053
 
 
1054
            if (data)
 
1055
              memset(data, 0, sizeof(mydata));
 
1056
            break;
 
1057
        }
 
1058
 
 
1059
        case PGEVT_CONNDESTROY:
 
1060
        {
 
1061
            PGEventConnDestroy *e = (PGEventConnDestroy *)evtInfo;
 
1062
            mydata *data = PQinstanceData(e-&#62;conn, myEventProc);
 
1063
 
 
1064
            /* free instance data because the conn is being destroyed */
 
1065
            if (data)
 
1066
              free_mydata(data);
 
1067
            break;
 
1068
        }
 
1069
 
 
1070
        case PGEVT_RESULTCREATE:
 
1071
        {
 
1072
            PGEventResultCreate *e = (PGEventResultCreate *)evtInfo;
 
1073
            mydata *conn_data = PQinstanceData(e-&#62;conn, myEventProc);
 
1074
            mydata *res_data = dup_mydata(conn_data);
 
1075
 
 
1076
            /* associate app specific data with result (copy it from conn) */
 
1077
            PQsetResultInstanceData(e-&#62;result, myEventProc, res_data);
 
1078
            break;
 
1079
        }
 
1080
 
 
1081
        case PGEVT_RESULTCOPY:
 
1082
        {
 
1083
            PGEventResultCopy *e = (PGEventResultCopy *)evtInfo;
 
1084
            mydata *src_data = PQresultInstanceData(e-&#62;src, myEventProc);
 
1085
            mydata *dest_data = dup_mydata(src_data);
 
1086
 
 
1087
            /* associate app specific data with result (copy it from a result) */
 
1088
            PQsetResultInstanceData(e-&#62;dest, myEventProc, dest_data);
 
1089
            break;
 
1090
        }
 
1091
 
 
1092
        case PGEVT_RESULTDESTROY:
 
1093
        {
 
1094
            PGEventResultDestroy *e = (PGEventResultDestroy *)evtInfo;
 
1095
            mydata *data = PQresultInstanceData(e-&#62;result, myEventProc);
 
1096
 
 
1097
            /* free instance data because the result is being destroyed */
 
1098
            if (data)
 
1099
              free_mydata(data);
 
1100
            break;
 
1101
        }
 
1102
 
 
1103
        /* unknown event id, just return TRUE. */
 
1104
        default:
 
1105
            break;
 
1106
    }
 
1107
 
 
1108
    return TRUE; /* event processing succeeded */
 
1109
}</PRE
 
1110
></DIV
 
1111
></DIV
 
1112
><DIV
 
1113
CLASS="NAVFOOTER"
 
1114
><HR
 
1115
ALIGN="LEFT"
 
1116
WIDTH="100%"><TABLE
 
1117
SUMMARY="Footer navigation table"
 
1118
WIDTH="100%"
 
1119
BORDER="0"
 
1120
CELLPADDING="0"
 
1121
CELLSPACING="0"
 
1122
><TR
 
1123
><TD
 
1124
WIDTH="33%"
 
1125
ALIGN="left"
 
1126
VALIGN="top"
 
1127
><A
 
1128
HREF="libpq-notice-processing.html"
 
1129
ACCESSKEY="P"
 
1130
>Prev</A
 
1131
></TD
 
1132
><TD
 
1133
WIDTH="34%"
 
1134
ALIGN="center"
 
1135
VALIGN="top"
 
1136
><A
 
1137
HREF="index.html"
 
1138
ACCESSKEY="H"
 
1139
>Home</A
 
1140
></TD
 
1141
><TD
 
1142
WIDTH="33%"
 
1143
ALIGN="right"
 
1144
VALIGN="top"
 
1145
><A
 
1146
HREF="libpq-envars.html"
 
1147
ACCESSKEY="N"
 
1148
>Next</A
 
1149
></TD
 
1150
></TR
 
1151
><TR
 
1152
><TD
 
1153
WIDTH="33%"
 
1154
ALIGN="left"
 
1155
VALIGN="top"
 
1156
>Notice Processing</TD
 
1157
><TD
 
1158
WIDTH="34%"
 
1159
ALIGN="center"
 
1160
VALIGN="top"
 
1161
><A
 
1162
HREF="libpq.html"
 
1163
ACCESSKEY="U"
 
1164
>Up</A
 
1165
></TD
 
1166
><TD
 
1167
WIDTH="33%"
 
1168
ALIGN="right"
 
1169
VALIGN="top"
 
1170
>Environment Variables</TD
 
1171
></TR
 
1172
></TABLE
 
1173
></DIV
 
1174
></BODY
 
1175
></HTML
 
1176
>
 
 
b'\\ No newline at end of file'