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