ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2020 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\"
5
.\" Permission to use, copy, modify, and distribute this software for any
6
.\" purpose with or without fee is hereby granted, provided that the above
7
.\" copyright notice and this permission notice appear in all copies.
8
.\"
9
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
.\"
17
.Dd $Mdocdate$
18
.Dt KJSON_PUTBOOL 3
19
.Os
20
.Sh NAME
21
.Nm kjson_putbool ,
22
.Nm kjson_putboolp
23
.Nd put Boolean content for kcgijson
24
.Sh LIBRARY
25
.Lb libkcgijson
26
.Sh SYNOPSIS
27
.In sys/types.h
28
.In stdarg.h
29
.In stdint.h
30
.In kcgi.h
31
.In kcgijson.h
32
.Ft enum kcgi_err
33
.Fo kjson_putbool
34
.Fa "struct kjsonreq *req"
35
.Fa "int v"
36
.Fc
37
.Ft enum kcgi_err
38
.Fo kjson_putboolp
39
.Fa "struct kjsonreq *req"
40
.Fa "const char *name"
41
.Fa "int v"
42
.Fc
43
.Sh DESCRIPTION
44
Write a Boolean
45
.Fa v ,
46
represented as zero for false and non-zero for true, to a context
47
.Fa req
48
initialised with
49
.Xr khtml_open 3 .
50
.Pp
51
The
52
.Fn kjson_putbool
53
form is for array scopes and
54
.Fn kjson_putboolp
55
for objects.
56
.Pp
57
Passing a
58
.Dv NULL
59
value to
60
.Fa name
61
for
62
.Fn kjson_putboolp ,
63
is equivalent to calling
64
.Fn kjson_putbool .
65
.Sh RETURN VALUES
66
Returns an
67
.Ft enum kcgi_err
68
indicating the error state.
69
.Bl -tag -width -Ds
70
.It Dv KCGI_OK
71
Success (not an error).
72
.It Dv KCGI_ENOMEM
73
Internal memory allocation failure.
74
.It Dv KCGI_HUP
75
The output connection has been terminated.
76
For FastCGI connections, the current connection should be released with
77
.Xr khttp_free 3
78
and parse loop reentered.
79
.It Dv KCGI_FORM
80
The connection is still expecting headers with
81
.Xr khttp_head 3 .
82
Indicates that
83
.Xr khttp_body 3
84
did not return with success or was not invoked.
85
For FastCGI connections, the current connection should be released with
86
.Xr khttp_free 3
87
and parse loop reentered.
88
.It Dv KCGI_SYSTEM
89
Internal system error writing to the output stream.
90
.It Dv KCGI_WRITER
91
The incorrect form was used for the current scope, for example, an
92
array-type write within an object.
93
.El
94
.Sh EXAMPLES
95
The following outputs a simple JSON document.
96
It assumes
97
.Va r
98
is a
99
.Vt struct kreq
100
pointer.
101
For brevity, it does not do any error checking.
102
.Bd -literal -offset indent
103
khttp_head(r, kresps[KRESP_STATUS],
104
  "%s", khttps[KHTTP_200]);
105
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
106
  "%s", kmimetypes[KMIME_APP_JSON]);
107
khttp_body(r);
108
kjson_open(&req, r);
109
kjson_obj_open(&req);
110
kjson_putboolp(&req, "bar", 1); /* true */
111
kjson_arrayp_open(&req, "baz");
112
kjson_putbool(&req, 0)); /* false */
113
kjson_close(&req);
114
.Ed
115
.Sh SEE ALSO
116
.Xr kcgijson 3
117
.Sh AUTHORS
118
Written by
119
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
120