1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_HSTSWRITEFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HSTS (3)
9  - CURLOPT_HSTSWRITEDATA (3)
10  - CURLOPT_HSTSWRITEFUNCTION (3)
11  - CURLOPT_HSTS_CTRL (3)
12---
13
14# NAME
15
16CURLOPT_HSTSWRITEFUNCTION - write callback for HSTS hosts
17
18# SYNOPSIS
19
20~~~c
21#include <curl/curl.h>
22
23struct curl_hstsentry {
24  char *name;
25  size_t namelen;
26  unsigned int includeSubDomains:1;
27  char expire[18]; /* YYYYMMDD HH:MM:SS [null-terminated] */
28};
29
30struct curl_index {
31  size_t index; /* the provided entry's "index" or count */
32  size_t total; /* total number of entries to save */
33};
34
35CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts,
36                      struct curl_index *count, void *clientp);
37
38CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite);
39~~~
40
41# DESCRIPTION
42
43Pass a pointer to your callback function, as the prototype shows above.
44
45This callback function gets called by libcurl repeatedly to allow the
46application to store the in-memory HSTS cache when libcurl is about to discard
47it.
48
49Set the *clientp* argument with the CURLOPT_HSTSWRITEDATA(3) option
50or it is NULL.
51When the callback is invoked, the *sts* pointer points to a populated
52struct: Read the hostname to 'name' (it is *namelen* bytes long and null
53terminated. The *includeSubDomains* field is non-zero if the entry matches
54subdomains. The *expire* string is a date stamp null-terminated string
55using the syntax YYYYMMDD HH:MM:SS.
56
57The callback should return *CURLSTS_OK* if it succeeded and is prepared to
58be called again (for another host) or *CURLSTS_DONE* if there is nothing
59more to do. It can also return *CURLSTS_FAIL* to signal error.
60
61This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to
62do that.
63
64# DEFAULT
65
66NULL - no callback.
67
68# PROTOCOLS
69
70This feature is only used for HTTP(S) transfer.
71
72# EXAMPLE
73
74~~~c
75struct priv {
76  void *custom;
77};
78
79static CURLSTScode hswr_cb(CURL *easy, struct curl_hstsentry *sts,
80                           struct curl_index *count, void *clientp)
81{
82  /* save the passed in HSTS data somewhere */
83  return CURLSTS_OK;
84}
85
86int main(void)
87{
88  CURL *curl = curl_easy_init();
89  if(curl) {
90    struct priv my_stuff;
91    CURLcode res;
92
93    /* set HSTS read callback */
94    curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hswr_cb);
95
96    /* pass in suitable argument to the callback */
97    curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &my_stuff);
98
99    res = curl_easy_perform(curl);
100  }
101}
102~~~
103
104# AVAILABILITY
105
106Added in 7.74.0
107
108# RETURN VALUE
109
110This returns CURLE_OK.
111