/
ts.h
2435 lines (1926 loc) · 98.9 KB
/
ts.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/** @file
Traffic Server SDK API header file
@section license License
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
@section developers Developers
Developers, when adding a new element to an enum, append it. DO NOT
insert it. Otherwise, binary compatibility of plugins will be broken!
*/
#ifndef __TS_API_H__
#define __TS_API_H__
#include <ts/apidefs.h>
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/* --------------------------------------------------------------------------
Memory */
#define TSmalloc(s) _TSmalloc((s), TS_RES_MEM_PATH)
#define TSrealloc(p, s) _TSrealloc((p), (s), TS_RES_MEM_PATH)
#define TSstrdup(p) _TSstrdup((p), -1, TS_RES_MEM_PATH)
#define TSstrndup(p, n) _TSstrdup((p), (n), TS_RES_MEM_PATH)
#define TSstrlcpy(d, s, l) _TSstrlcpy((d), (s), (l))
#define TSstrlcat(d, s, l) _TSstrlcat((d), (s), (l))
#define TSfree(p) _TSfree(p)
tsapi void *_TSmalloc(size_t size, const char *path);
tsapi void *_TSrealloc(void *ptr, size_t size, const char *path);
tsapi char *_TSstrdup(const char *str, int64_t length, const char *path);
tsapi size_t _TSstrlcpy(char *dst, const char *str, size_t siz);
tsapi size_t _TSstrlcat(char *dst, const char *str, size_t siz);
tsapi void _TSfree(void *ptr);
/* --------------------------------------------------------------------------
Component object handles */
/**
Releases the TSMLoc mloc created from the TSMLoc parent.
If there is no parent TSMLoc, use TS_NULL_MLOC.
@param bufp marshal buffer containing the TSMLoc handle to be
released.
@param parent location of the parent object from which the handle
was created.
@param mloc location of the handle to be released.
*/
tsapi TSReturnCode TSHandleMLocRelease(TSMBuffer bufp, TSMLoc parent, TSMLoc mloc);
/* --------------------------------------------------------------------------
Install and plugin locations */
/**
Gets the path of the directory in which Traffic Server is installed.
Use this function to specify the location of files that the
plugin uses.
@return pointer to Traffic Server install directory.
*/
tsapi const char *TSInstallDirGet(void);
/**
Gets the path of the directory of Traffic Server configuration.
@return pointer to Traffic Server configuration directory.
*/
tsapi const char *TSConfigDirGet(void);
/**
Gets the path of the directory of Traffic Server runtime.
@return pointer to Traffic Server runtime directory.
*/
tsapi const char *TSRuntimeDirGet(void);
/**
Gets the path of the plugin directory relative to the Traffic Server
install directory. For example, to open the file "config_ui.txt" in
the plugin directory:
@code
TSfopen("TSPluginInstallDirGet()/TSPluginDirGet()/config_ui.txt");
@endcode
@return pointer to plugin directory relative to Traffic Server install
directory.
*/
tsapi const char *TSPluginDirGet(void);
/* --------------------------------------------------------------------------
Traffic Server Version */
/**
Gets the version of Traffic Server currently running. Use this
function to make sure that the plugin version and Traffic Server
version are compatible. See the SDK sample code for usage.
@return pointer to version of Traffic Server running the plugin.
*/
tsapi const char *TSTrafficServerVersionGet(void);
/** Get the major version of Traffic Server currently running.
This is the same as the first element of the string
returned by @c TSTrafficServerVersionGet
@return The major version as an integer.
*/
int TSTrafficServerVersionGetMajor(void);
/** Get the minor version of Traffic Server currently running.
This is the same as the second element of the string
returned by @c TSTrafficServerVersionGet
@return The minor version as an integer.
*/
int TSTrafficServerVersionGetMinor(void);
/** Get the patch version of Traffic Server currently running.
This is the same as the third element of the string
returned by @c TSTrafficServerVersionGet
@return The patch version as an integer.
*/
int TSTrafficServerVersionGetPatch(void);
/* --------------------------------------------------------------------------
Plugin registration */
/**
This function registers your plugin with a particular version
of Traffic Server SDK. Use this function to make sure that the
Traffic Server version currently running also supports your plugin.
See the SDK sample code for usage.
@param plugin_info contains registration information about your
plugin. See TSPluginRegistrationInfo.
@return TS_ERROR if the plugin registration failed.
*/
tsapi TSReturnCode TSPluginRegister(TSPluginRegistrationInfo const *plugin_info);
/* --------------------------------------------------------------------------
Files */
/**
Opens a file for reading or writing and returns a descriptor for
accessing the file. The current implementation cannot open a file
for both reading or writing. See the SDK Programmer's Guide for
sample code.
@param filename file to be opened.
@param mode specifies whether to open the file for reading or
writing. If mode is "r" then the file is opened for reading.
If mode is "w" then the file is opened for writing. Currently
"r" and "w" are the only two valid modes for opening a file.
@return descriptor for the file that TSfopen opens. Descriptors of
type TSFile can be greater than 256.
*/
tsapi TSFile TSfopen(const char *filename, const char *mode);
/**
Closes the file to which filep points and frees the data structures
and buffers associated with it. If the file was opened for writing,
any pending data is flushed.
@param filep file to be closed.
*/
tsapi void TSfclose(TSFile filep);
/**
Attempts to read length bytes of data from the file pointed to by
filep into the buffer buf.
@param filep name of the file to read from.
@param buf buffer to read into.
@param length amount of data to read, in bytes.
@return number of bytes read. If end of the file, it returns 0.
If the file was not opened for reading or if an error occurs
while reading the file, it returns -1.
*/
tsapi size_t TSfread(TSFile filep, void *buf, size_t length);
/**
Attempts to write length bytes of data from the buffer buf
to the file filep. Make sure that filep is open for writing.
You might want to check the number of bytes written (TSfwrite()
returns this value) against the value of length. If it is less,
there might be insufficient space on disk, for example.
@param filep file to write into.
@param buf buffer containing the data to be written.
@param length amount of data to write to filep, in bytes.
@return number of bytes written to filep. If the file was not
opened for writing, it returns -1. If an error occurs while
writing, it returns the number of bytes successfully written.
*/
tsapi size_t TSfwrite(TSFile filep, const void *buf, size_t length);
/**
Flushes pending data that has been buffered up in memory from
previous calls to TSfwrite().
@param filep file to flush.
*/
tsapi void TSfflush(TSFile filep);
/**
Reads a line from the file pointed to by filep into the buffer buf.
Lines are terminated by a line feed character, '\n'. The line
placed in the buffer includes the line feed character and is
terminated with a NULL. If the line is longer than length bytes
then only the first length-minus-1 bytes are placed in buf.
@param filep file to read from.
@param buf buffer to read into.
@param length size of the buffer to read into.
@return pointer to the string read into the buffer buf.
*/
tsapi char *TSfgets(TSFile filep, char *buf, size_t length);
/* --------------------------------------------------------------------------
Error logging */
/**
Writes printf-style error messages to the Traffic Server error
log. One advantage of TSError over printf is that each call is
atomically placed into the error log and is not garbled with other
error entries. This is not an issue in single-threaded programs
but is a definite nuisance in multi-threaded programs.
@param fmt printf format description.
@param ... argument for the printf format description.
*/
tsapi void TSError(const char *fmt, ...) TS_PRINTFLIKE(1, 2);
/* --------------------------------------------------------------------------
Assertions */
tsapi void _TSReleaseAssert(const char *txt, const char *f, int l) TS_NORETURN;
tsapi int _TSAssert(const char *txt, const char *f, int l);
#define TSReleaseAssert(EX) ((void)((EX) ? (void)0 : _TSReleaseAssert(#EX, __FILE__, __LINE__)))
#define TSAssert(EX) (void)((EX) || (_TSAssert(#EX, __FILE__, __LINE__)))
/* --------------------------------------------------------------------------
Marshal buffers */
/**
Creates a new marshal buffer and initializes the reference count
to 1.
*/
tsapi TSMBuffer TSMBufferCreate(void);
/**
Ignores the reference count and destroys the marshal buffer bufp.
The internal data buffer associated with the marshal buffer is
also destroyed if the marshal buffer allocated it.
@param bufp marshal buffer to be destroyed.
*/
tsapi TSReturnCode TSMBufferDestroy(TSMBuffer bufp);
/* --------------------------------------------------------------------------
URLs */
/**
Creates a new URL within the marshal buffer bufp. Returns a
location for the URL within the marshal buffer.
@param bufp marshal buffer containing the new URL.
@param locp pointer to a TSMLoc to store the MLoc into.
*/
tsapi TSReturnCode TSUrlCreate(TSMBuffer bufp, TSMLoc *locp);
/**
Destroys the URL located at url_loc within the marshal buffer
bufp. Do not forget to release the TSMLoc url_loc with a call
to TSHandleMLocRelease().
@param bufp marshal buffer containing the URL to be destroyed.
@param offset location of the URL to be destroyed.
*/
/** @deprecated There is no reason to destroy the URL, just release
the marshal buffers. Should be removed for v5.0.0 */
tsapi TS_DEPRECATED TSReturnCode TSUrlDestroy(TSMBuffer bufp, TSMLoc offset);
/**
Copies the URL located at src_url within src_bufp to a URL
location within the marshal buffer dest_bufp, and returns the
TSMLoc location of the copied URL. Unlike TSUrlCopy(), you do
not have to create the destination URL before cloning. Release
the returned TSMLoc handle with a call to TSHandleMLocRelease().
@param dest_bufp marshal buffer containing the cloned URL.
@param src_bufp marshal buffer containing the URL to be cloned.
@param src_url location of the URL to be cloned, within the marshal
buffer src_bufp.
@param locp pointer to a TSMLoc to store the MLoc into.
*/
tsapi TSReturnCode TSUrlClone(TSMBuffer dest_bufp, TSMBuffer src_bufp, TSMLoc src_url, TSMLoc *locp);
/**
Copies the contents of the URL at location src_loc within the
marshal buffer src_bufp to the location dest_loc within the marshal
buffer dest_bufp. TSUrlCopy() works correctly even if src_bufp
and dest_bufp point to different marshal buffers. Important: create
the destination URL before copying into it. Use TSUrlCreate().
@param dest_bufp marshal buffer to contain the copied URL.
@param dest_offset location of the URL to be copied.
@param src_bufp marshal buffer containing the source URL.
@param src_offset location of the source URL within src_bufp.
*/
tsapi TSReturnCode TSUrlCopy(TSMBuffer dest_bufp, TSMLoc dest_offset, TSMBuffer src_bufp, TSMLoc src_offset);
/**
Formats a URL stored in an TSMBuffer into an TSIOBuffer.
@param bufp marshal buffer contain the URL to be printed.
@param offset location of the URL within bufp.
@param iobufp destination TSIOBuffer for the URL.
*/
tsapi void TSUrlPrint(TSMBuffer bufp, TSMLoc offset, TSIOBuffer iobufp);
/**
Parses a URL. The start pointer is both an input and an output
parameter and marks the start of the URL to be parsed. After
a successful parse, the start pointer equals the end pointer.
The end pointer must be one byte after the last character you
want to parse. The URL parsing routine assumes that everything
between start and end is part of the URL. It is up to higher level
parsing routines, such as TSHttpHdrParseReq(), to determine the
actual end of the URL. Returns TS_PARSE_ERROR if an error occurs,
otherwise TS_PARSE_DONE is returned to indicate success.
@param bufp marshal buffer containing the URL to be parsed.
@param offset location of the URL to be parsed.
@param start points to the start of the URL to be parsed AND at
the end of a successful parse it will equal the end pointer.
@param end must be one byte after the last character.
@return TS_PARSE_ERROR or TS_PARSE_DONE.
*/
tsapi TSParseResult TSUrlParse(TSMBuffer bufp, TSMLoc offset, const char **start, const char *end);
/**
Calculates the length of the URL located at url_loc within the
marshal buffer bufp if it were returned as a string. This length
is the same as the length returned by TSUrlStringGet().
@param bufp marshal buffer containing the URL whose length you want.
@param offset location of the URL within the marshal buffer bufp.
@return string length of the URL.
*/
tsapi int TSUrlLengthGet(TSMBuffer bufp, TSMLoc offset);
/**
Constructs a string representation of the URL located at url_loc
within bufp. TSUrlStringGet() stores the length of the allocated
string in the parameter length. This is the same length that
TSUrlLengthGet() returns. The returned string is allocated by a
call to TSmalloc(). It should be freed by a call to TSfree().
The length parameter must present, providing storage for the URL
string length value.
Note: To get the effective URL from a request, use the alternative
TSHttpTxnEffectiveUrlStringGet API.
@param bufp marshal buffer containing the URL you want to get.
@param offset location of the URL within bufp.
@param length string length of the URL.
@return The URL as a string.
*/
tsapi char *TSUrlStringGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Retrieves the scheme portion of the URL located at url_loc within
the marshal buffer bufp. TSUrlSchemeGet() places the length of
the string in the length argument. If the length is NULL then no
attempt is made to dereference it.
@param bufp marshal buffer storing the URL.
@param offset location of the URL within bufp.
@param length length of the returned string.
@return The scheme portion of the URL, as a string.
*/
tsapi const char *TSUrlSchemeGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the scheme portion of the URL located at url_loc within
the marshal buffer bufp to the string value. If length is -1
then TSUrlSchemeSet() assumes that value is null-terminated.
Otherwise, the length of the string value is taken to be length.
TSUrlSchemeSet() copies the string to within bufp, so it is OK
to modify or delete value after calling TSUrlSchemeSet().
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param value value to set the URL's scheme to.
@param length string stored in value.
*/
tsapi TSReturnCode TSUrlSchemeSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/* --------------------------------------------------------------------------
Internet specific URLs */
/**
Retrieves the user portion of the URL located at url_loc
within bufp. Note: the returned string is not guaranteed to
be null-terminated.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param length length of the returned string.
@return user portion of the URL.
*/
tsapi const char *TSUrlUserGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the user portion of the URL located at url_loc within bufp
to the string value. If length is -1 then TSUrlUserSet() assumes
that value is null-terminated. Otherwise, the length of the string
value is taken to be length. TSUrlUserSet() copies the string to
within bufp, so it is OK to modify or delete value after calling
TSUrlUserSet().
@param bufp marshal buffer containing the URL.
@param offset location of the URL whose user is to be set.
@param value holds the new user name.
@param length string length of value.
*/
tsapi TSReturnCode TSUrlUserSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/**
Retrieves the password portion of the URL located at url_loc
within bufp. TSUrlPasswordGet() places the length of the returned
string in the length argument. Note: the returned string is
not guaranteed to be null-terminated.
@param bufp marshal buffer containing the URL.
@param offset
@param length of the returned password string.
@return password portion of the URL.
*/
tsapi const char *TSUrlPasswordGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the password portion of the URL located at url_loc within
bufp to the string value. If length is -1 then TSUrlPasswordSet()
assumes that value is null-terminated. Otherwise, the length
of value is taken to be length. TSUrlPasswordSet() copies the
string to within bufp, so it is okay to modify or delete value
after calling TSUrlPasswordSet().
@param bufp marshal buffer containing the URL.
@param offset
@param value new password.
@param length of the new password.
*/
tsapi TSReturnCode TSUrlPasswordSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/**
Retrieves the host portion of the URL located at url_loc
within bufp. Note: the returned string is not guaranteed to be
null-terminated.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param length of the returned string.
@return Host portion of the URL.
*/
tsapi const char *TSUrlHostGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the host portion of the URL at url_loc to the string value.
If length is -1 then TSUrlHostSet() assumes that value is
null-terminated. Otherwise, the length of the string value is
taken to be length. The string is copied to within bufp, so you
can modify or delete value after calling TSUrlHostSet().
@param bufp marshal buffer containing the URL to modify.
@param offset location of the URL.
@param value new host name for the URL.
@param length string length of the new host name of the URL.
*/
tsapi TSReturnCode TSUrlHostSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/**
Retrieves the port portion of the URL located at url_loc.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@return port portion of the URL.
*/
tsapi int TSUrlPortGet(TSMBuffer bufp, TSMLoc offset);
/**
Sets the port portion of the URL located at url_loc.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param port new port setting for the URL.
*/
tsapi TSReturnCode TSUrlPortSet(TSMBuffer bufp, TSMLoc offset, int port);
/* --------------------------------------------------------------------------
HTTP specific URLs */
/**
Retrieves the path portion of the URL located at url_loc within
bufp. TSUrlPathGet() places the length of the returned string in
the length argument. Note: the returned string is not guaranteed to
be null-terminated.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param length of the returned string.
@return path portion of the URL.
*/
tsapi const char *TSUrlPathGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the path portion of the URL located at url_loc within bufp
to the string value. If length is -1 then TSUrlPathSet() assumes
that value is null-terminated. Otherwise, the length of the value
is taken to be length. TSUrlPathSet() copies the string into bufp,
so you can modify or delete value after calling TSUrlPathSet().
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param value new path string for the URL.
@param length of the new path string.
*/
tsapi TSReturnCode TSUrlPathSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/* --------------------------------------------------------------------------
FTP specific URLs */
/**
Retrieves the FTP type of the URL located at url_loc within bufp.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@return FTP type of the URL.
*/
tsapi int TSUrlFtpTypeGet(TSMBuffer bufp, TSMLoc offset);
/**
Sets the FTP type portion of the URL located at url_loc within
bufp to the value type.
@param bufp marshal buffer containing the URL.
@param offset location of the URL to modify.
@param type new FTP type for the URL.
*/
tsapi TSReturnCode TSUrlFtpTypeSet(TSMBuffer bufp, TSMLoc offset, int type);
/* --------------------------------------------------------------------------
HTTP specific URLs */
/**
Retrieves the HTTP params portion of the URL located at url_loc
within bufp. The length of the returned string is in the length
argument. Note: the returned string is not guaranteed to be
null-terminated.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param length of the returned string.
@return HTTP params portion of the URL.
*/
tsapi const char *TSUrlHttpParamsGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the HTTP params portion of the URL located at url_loc within
bufp to the string value. If length is -1 that TSUrlHttpParamsSet()
assumes that value is null-terminated. Otherwise, the length of
the string value is taken to be length. TSUrlHttpParamsSet()
copies the string to within bufp, so you can modify or delete
value after calling TSUrlHttpParamsSet().
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param value HTTP params string to set in the URL.
@param length string length of the new HTTP params value.
*/
tsapi TSReturnCode TSUrlHttpParamsSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/**
Retrieves the HTTP query portion of the URL located at url_loc
within bufp. The length of the returned string is in the length
argument. Note: the returned string is not guaranteed to be
null-terminated.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param length of the returned string.
@return HTTP query portion of the URL.
*/
tsapi const char *TSUrlHttpQueryGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the HTTP query portion of the URL located at url_loc within
bufp to value. If length is -1, the string value is assumed to
be null-terminated; otherwise, the length of value is taken to be
length. TSUrlHttpQuerySet() copies the string to within bufp, so
you can modify or delete value after calling TSUrlHttpQuerySet().
@param bufp marshal buffer containing the URL.
@param offset location of the URL within bufp.
@param value new HTTP query string for the URL.
@param length of the new HTTP query string.
*/
tsapi TSReturnCode TSUrlHttpQuerySet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/**
Retrieves the HTTP fragment portion of the URL located at url_loc
within bufp. The length of the returned string is in the length
argument. Note: the returned string is not guaranteed to be
null-terminated.
@param bufp marshal buffer containing the URL.
@param offset location of the URL.
@param length of the returned string.
@return HTTP fragment portion of the URL.
*/
tsapi const char *TSUrlHttpFragmentGet(TSMBuffer bufp, TSMLoc offset, int *length);
/**
Sets the HTTP fragment portion of the URL located at url_loc
within bufp to value. If length is -1, the string value is
assumed to be null-terminated; otherwise, the length of value
is taken to be length. TSUrlHttpFragmentSet() copies the string
to within bufp, so you can modify or delete value after calling
TSUrlHttpFragmentSet().
@param bufp marshal buffer containing the URL.
@param offset location of the URL within bufp.
@param value new HTTP fragment string for the URL.
@param length of the new HTTP query string.
*/
tsapi TSReturnCode TSUrlHttpFragmentSet(TSMBuffer bufp, TSMLoc offset, const char *value, int length);
/**
Perform percent-encoding of the string in the buffer, storing the
new string in the destination buffer. The length parameter will be
set to the new (encoded) string length, or 0 if the encoding failed.
@param str the string buffer to encode.
@param str_len length of the string buffer.
@param dst destination buffer.
@param dst_size size of the destination buffer.
@param length amount of data written to the destination buffer.
@param map optional (can be NULL) map of characters to encode.
*/
tsapi TSReturnCode TSStringPercentEncode(const char *str, int str_len, char *dst, size_t dst_size, size_t *length,
const unsigned char *map);
/**
Similar to TSStringPercentEncode(), but works on a URL object.
@param bufp marshal buffer containing the URL.
@param offset location of the URL within bufp.
@param dst destination buffer.
@param dst_size size of the destination buffer.
@param length amount of data written to the destination buffer.
@param map optional (can be NULL) map of characters to encode.
*/
tsapi TSReturnCode TSUrlPercentEncode(TSMBuffer bufp, TSMLoc offset, char *dst, size_t dst_size, size_t *length,
const unsigned char *map);
/**
Perform percent-decoding of the string in the buffer, writing
to the output buffer. The source and destination can be the same,
in which case they overwrite. The decoded string is always
guaranteed to be no longer than the source string.
@param str the string to decode (and possibly write to).
@param str_len length of the input string (or 0).
@param dst output buffer (can be the same as src).
@param dst_len size of the output buffer.
@param length amount of data written to the destination buffer.
*/
tsapi TSReturnCode TSStringPercentDecode(const char *str, size_t str_len, char *dst, size_t dst_size, size_t *length);
/* --------------------------------------------------------------------------
MIME headers */
/**
Creates a MIME parser. The parser's data structure contains
information about the header being parsed. A single MIME
parser can be used multiple times, though not simultaneously.
Before being used again, the parser must be cleared by calling
TSMimeParserClear().
*/
tsapi TSMimeParser TSMimeParserCreate(void);
/**
Clears the specified MIME parser so that it can be used again.
@param parser to be cleared.
*/
tsapi void TSMimeParserClear(TSMimeParser parser);
/**
Destroys the specified MIME parser and frees the associated memory.
@param parser to destroy.
*/
tsapi void TSMimeParserDestroy(TSMimeParser parser);
/**
Creates a new MIME header within bufp. Release with a call to
TSHandleMLocRelease().
@param bufp marshal buffer to contain the new MIME header.
@param locp buffer pointer to contain the MLoc
*/
tsapi TSReturnCode TSMimeHdrCreate(TSMBuffer bufp, TSMLoc *locp);
/**
Destroys the MIME header located at hdr_loc within bufp.
@param bufp marshal buffer containing the MIME header to destroy.
@param offset location of the MIME header.
*/
tsapi TSReturnCode TSMimeHdrDestroy(TSMBuffer bufp, TSMLoc offset);
/**
Copies a specified MIME header to a specified marshal buffer,
and returns the location of the copied MIME header within the
destination marshal buffer. Unlike TSMimeHdrCopy(), you do not
have to create the destination MIME header before cloning. Release
the returned TSMLoc handle with a call to TSHandleMLocRelease().
@param dest_bufp destination marshal buffer.
@param src_bufp source marshal buffer.
@param src_hdr location of the source MIME header.
@param locp where to store the location of the copied MIME header.
*/
tsapi TSReturnCode TSMimeHdrClone(TSMBuffer dest_bufp, TSMBuffer src_bufp, TSMLoc src_hdr, TSMLoc *locp);
/**
Copies the contents of the MIME header located at src_loc
within src_bufp to the MIME header located at dest_loc within
dest_bufp. TSMimeHdrCopy() works correctly even if src_bufp and
dest_bufp point to different marshal buffers. Important: you must
create the destination MIME header before copying into it--use
TSMimeHdrCreate().
@param dest_bufp is the destination marshal buffer.
@param dest_offset
@param src_bufp is the source marshal buffer.
@param src_offset
*/
tsapi TSReturnCode TSMimeHdrCopy(TSMBuffer dest_bufp, TSMLoc dest_offset, TSMBuffer src_bufp, TSMLoc src_offset);
/**
Formats the MIME header located at hdr_loc within bufp into the
TSIOBuffer iobufp.
@param bufp marshal buffer containing the header to be copied to
an TSIOBuffer.
@param offset
@param iobufp target TSIOBuffer.
*/
tsapi void TSMimeHdrPrint(TSMBuffer bufp, TSMLoc offset, TSIOBuffer iobufp);
/**
Parses a MIME header. The MIME header must have already been
allocated and both bufp and hdr_loc must point within that header.
It is possible to parse a MIME header a single byte at a time
using repeated calls to TSMimeHdrParse(). As long as an error
does not occur, TSMimeHdrParse() consumes each single byte and
asks for more.
@param parser parses the specified MIME header.
@param bufp marshal buffer containing the MIME header to be parsed.
@param offset
@param start both an input and output. On input, the start
argument points to the current position of the buffer being
parsed. On return, start is modified to point past the last
character parsed.
@param end points to one byte after the end of the buffer.
@return One of 3 possible int values:
- TS_PARSE_ERROR if there is a parsing error.
- TS_PARSE_DONE is returned when a "\r\n\r\n" pattern is
encountered, indicating the end of the header.
- TS_PARSE_CONT is returned if parsing of the header stopped
because the end of the buffer was reached.
*/
tsapi TSParseResult TSMimeHdrParse(TSMimeParser parser, TSMBuffer bufp, TSMLoc offset, const char **start, const char *end);
/**
Calculates the length of the MIME header located at hdr_loc if it
were returned as a string. This the length of the MIME header in
its unparsed form.
@param bufp marshal buffer containing the MIME header.
@param offset location of the MIME header.
@return string length of the MIME header located at hdr_loc.
*/
tsapi int TSMimeHdrLengthGet(TSMBuffer bufp, TSMLoc offset);
/**
Removes and destroys all the MIME fields within the MIME header
located at hdr_loc within the marshal buffer bufp.
@param bufp marshal buffer containing the MIME header.
@param offset location of the MIME header.
*/
tsapi TSReturnCode TSMimeHdrFieldsClear(TSMBuffer bufp, TSMLoc offset);
/**
Returns a count of the number of MIME fields within the MIME header
located at hdr_loc within the marshal buffer bufp.
@param bufp marshal buffer containing the MIME header.
@param offset location of the MIME header within bufp.
@return number of MIME fields within the MIME header located
at hdr_loc.
*/
tsapi int TSMimeHdrFieldsCount(TSMBuffer bufp, TSMLoc offset);
/**
Retrieves the location of a specified MIME field within the
MIME header located at hdr_loc within bufp. The idx parameter
specifies which field to retrieve. The fields are numbered from 0
to TSMimeHdrFieldsCount(bufp, hdr_loc) - 1. If idx does not lie
within that range then TSMimeHdrFieldGet returns 0. Release the
returned handle with a call to TSHandleMLocRelease.
@param bufp marshal buffer containing the MIME header.
@param hdr location of the MIME header.
@param idx index of the field to get with base at 0.
@return location of the specified MIME field.
*/
tsapi TSMLoc TSMimeHdrFieldGet(TSMBuffer bufp, TSMLoc hdr, int idx);
/**
Retrieves the TSMLoc location of a specified MIME field from within
the MIME header located at hdr. The name and length parameters
specify which field to retrieve. For each MIME field in the MIME
header, a case insensitive string comparison is done between
the field name and name. If TSMimeHdrFieldFind() cannot find the
requested field, it returns TS_NULL_MLOC. Release the returned
TSMLoc handle with a call to TSHandleMLocRelease().
@param bufp marshal buffer containing the MIME header field to find.
@param hdr location of the MIME header containing the field.
@param name of the field to retrieve.
@param length string length of the string name. If length is -1,
then name is assumed to be null-terminated.
@return location of the requested MIME field. If the field could
not be found, returns TS_NULL_MLOC.
*/
tsapi TSMLoc TSMimeHdrFieldFind(TSMBuffer bufp, TSMLoc hdr, const char *name, int length);
/**
Returns the TSMLoc location of a specified MIME field from within
the MIME header located at hdr. The retrieved_str parameter
specifies which field to retrieve. For each MIME field in the
MIME header, a pointer comparison is done between the field name
and retrieved_str. This is a much quicker retrieval function
than TSMimeHdrFieldFind() since it obviates the need for a
string comparison. However, retrieved_str must be one of the
predefined field names of the form TS_MIME_FIELD_XXX for the
call to succeed. Release the returned TSMLoc handle with a call
to TSHandleMLocRelease().
@param bufp marshal buffer containing the MIME field.
@param hdr location of the MIME header containing the field.
@param retrieved_str specifies the field to retrieve. Must be
one of the predefined field names of the form TS_MIME_FIELD_XXX.
@return location of the requested MIME field. If the requested
field cannot be found, returns 0.
*/
tsapi TSReturnCode TSMimeHdrFieldAppend(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
/**
Removes the MIME field located at field within bufp from the
header located at hdr within bufp. If the specified field cannot
be found in the list of fields associated with the header then
nothing is done.
Note: removing the field does not destroy the field, it only
detaches the field, hiding it from the printed output. The field
can be reattached with a call to TSMimeHdrFieldAppend(). If you
do not use the detached field you should destroy it with a call to
TSMimeHdrFieldDestroy() and release the handle field with a call
to TSHandleMLocRelease().
@param bufp contains the MIME field to remove.
@param hdr location of the header containing the MIME field to
be removed. This header could be an HTTP header or MIME header.
@param field is the location of the field to remove.
*/
tsapi TSReturnCode TSMimeHdrFieldRemove(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
tsapi TSReturnCode TSMimeHdrFieldCreate(TSMBuffer bufp, TSMLoc hdr, TSMLoc *locp);
/****************************************************************************
* Create a new field and assign it a name all in one call
****************************************************************************/
tsapi TSReturnCode TSMimeHdrFieldCreateNamed(TSMBuffer bufp, TSMLoc mh_mloc, const char *name, int name_len, TSMLoc *locp);
/**
Destroys the MIME field located at field within bufp. You must
release the TSMLoc field with a call to TSHandleMLocRelease().
@param bufp contains the MIME field to be destroyed.
@param hdr location of the parent header containing the field
to be destroyed. This could be the location of a MIME header or
HTTP header.
@param field location of the field to be destroyed.
*/
tsapi TSReturnCode TSMimeHdrFieldDestroy(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
tsapi TSReturnCode TSMimeHdrFieldClone(TSMBuffer dest_bufp, TSMLoc dest_hdr, TSMBuffer src_bufp, TSMLoc src_hdr, TSMLoc src_field,
TSMLoc *locp);
tsapi TSReturnCode TSMimeHdrFieldCopy(TSMBuffer dest_bufp, TSMLoc dest_hdr, TSMLoc dest_field, TSMBuffer src_bufp, TSMLoc src_hdr,
TSMLoc src_field);
tsapi TSReturnCode TSMimeHdrFieldCopyValues(TSMBuffer dest_bufp, TSMLoc dest_hdr, TSMLoc dest_field, TSMBuffer src_bufp,
TSMLoc src_hdr, TSMLoc src_field);
tsapi TSMLoc TSMimeHdrFieldNext(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
tsapi TSMLoc TSMimeHdrFieldNextDup(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
tsapi int TSMimeHdrFieldLengthGet(TSMBuffer bufp, TSMLoc hdr, TSMLoc field);
tsapi const char *TSMimeHdrFieldNameGet(TSMBuffer bufp, TSMLoc hdr, TSMLoc field, int *length);
tsapi TSReturnCode TSMimeHdrFieldNameSet(TSMBuffer bufp, TSMLoc hdr, TSMLoc field, const char *name, int length);