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_PUTSTRING 3
19
.Os
20
.Sh NAME
21
.Nm kjson_putstring ,
22
.Nm kjson_putstringp ,
23
.Nm kjson_string_puts
24
.Nd put string content for kcgijson
25
.Sh LIBRARY
26
.Lb libkcgijson
27
.Sh SYNOPSIS
28
.In sys/types.h
29
.In stdarg.h
30
.In stdint.h
31
.In kcgi.h
32
.In kcgijson.h
33
.Ft enum kcgi_err
34
.Fo kjson_putstring
35
.Fa "struct kjsonreq *req"
36
.Fa "const char *v"
37
.Fc
38
.Ft enum kcgi_err
39
.Fo kjson_putstringp
40
.Fa "struct kjsonreq *req"
41
.Fa "const char *name"
42
.Fa "const char *v"
43
.Fc
44
.Ft enum kcgi_err
45
.Fo kjson_string_puts
46
.Fa "struct kjsonreq *req"
47
.Fa "const char *v"
48
.Fc
49
.Sh DESCRIPTION
50
Write a string
51
.Fa v ,
52
to a context
53
.Fa req
54
initialised with
55
.Xr khtml_open 3 .
56
If
57
.Fa v
58
is
59
.Dv NULL ,
60
do nothing and return
61
.Dv KCGI_OK .
62
.Pp
63
The
64
.Fn kjson_putstring
65
form is for array scopes,
66
.Fn kjson_putstringp
67
for objects, and
68
.Fn kjson_string_puts
69
for open strings.
70
.Pp
71
All values are JSON escaped so that content cannot prematurely end its
72
context.
73
.Pp
74
Passing a
75
.Dv NULL
76
value to
77
.Fa name
78
for
79
.Fn kjson_putstringp ,
80
is equivalent to calling
81
.Fn kjson_putstring .
82
.Sh RETURN VALUES
83
Returns an
84
.Ft enum kcgi_err
85
indicating the error state.
86
.Bl -tag -width -Ds
87
.It Dv KCGI_OK
88
Success (not an error).
89
.It Dv KCGI_ENOMEM
90
Internal memory allocation failure.
91
.It Dv KCGI_HUP
92
The output connection has been terminated.
93
For FastCGI connections, the current connection should be released with
94
.Xr khttp_free 3
95
and parse loop reentered.
96
.It Dv KCGI_FORM
97
The connection is still expecting headers with
98
.Xr khttp_head 3 .
99
Indicates that
100
.Xr khttp_body 3
101
did not return with success or was not invoked.
102
For FastCGI connections, the current connection should be released with
103
.Xr khttp_free 3
104
and parse loop reentered.
105
.It Dv KCGI_SYSTEM
106
Internal system error writing to the output stream.
107
.It Dv KCGI_WRITER
108
The incorrect form was used for the current scope, for example, an
109
array-type write within an object.
110
.El
111
.Sh EXAMPLES
112
The following outputs a simple JSON document.
113
It assumes
114
.Va r
115
is a
116
.Vt struct kreq
117
pointer.
118
For brevity, it does not do any error checking.
119
.Bd -literal -offset indent
120
khttp_head(r, kresps[KRESP_STATUS],
121
  "%s", khttps[KHTTP_200]);
122
khttp_head(r, kresps[KRESP_CONTENT_TYPE],
123
  "%s", kmimetypes[KMIME_APP_JSON]);
124
khttp_body(r);
125
kjson_open(&req, r);
126
kjson_obj_open(&req);
127
kjson_putstringp(&req, "bar", "shbar");
128
kjson_arrayp_open(&req, "baz");
129
kjson_putstring(&req, "xyzzy"));
130
kjson_close(&req);
131
.Ed
132
.Sh SEE ALSO
133
.Xr kcgijson 3
134
.Sh AUTHORS
135
Written by
136
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
137