GMimeAutocryptHeader: GMime 3.0 Reference Manual

## GMimeAutocryptHeader

GMimeAutocryptHeader — A header containing cryptographic information about the sending address

## Functions

GMimeAutocryptHeader * | g_mime_autocrypt_header_new ()
GMimeAutocryptHeader * | g_mime_autocrypt_header_new_from_string ()
InternetAddressMailbox * | g_mime_autocrypt_header_get_address ()
void | g_mime_autocrypt_header_set_address ()
void | g_mime_autocrypt_header_set_address_from_string ()
const char * | g_mime_autocrypt_header_get_address_as_string ()
GMimeAutocryptPreferEncrypt | g_mime_autocrypt_header_get_prefer_encrypt ()
void | g_mime_autocrypt_header_set_prefer_encrypt ()
GBytes * | g_mime_autocrypt_header_get_keydata ()
void | g_mime_autocrypt_header_set_keydata ()
GDateTime * | g_mime_autocrypt_header_get_effective_date ()
void | g_mime_autocrypt_header_set_effective_date ()
gboolean | g_mime_autocrypt_header_is_complete ()
char * | g_mime_autocrypt_header_to_string ()
int | g_mime_autocrypt_header_compare ()
void | g_mime_autocrypt_header_clone ()
GMimeAutocryptHeaderList * | g_mime_autocrypt_header_list_new ()
guint | g_mime_autocrypt_header_list_add_missing_addresses ()
void | g_mime_autocrypt_header_list_add ()
guint | g_mime_autocrypt_header_list_get_count ()
GMimeAutocryptHeader * | g_mime_autocrypt_header_list_get_header_at ()
GMimeAutocryptHeader * | g_mime_autocrypt_header_list_get_header_for_address ()
void | g_mime_autocrypt_header_list_remove_incomplete ()

## Types and Values

enum | GMimeAutocryptPreferEncrypt
struct | GMimeAutocryptHeader
struct | GMimeAutocryptHeaderList

## Description

A GMimeAutocryptHeader is an object containing information derived from a message about the sender's cryptographic keys and preferences. It can be used in conjunction with local storage and business logic to make a better user experience for encrypted e-mail.

## Functions

### g_mime_autocrypt_header_new ()

    GMimeAutocryptHeader *
    g_mime_autocrypt_header_new (void);

Creates a new GMimeAutocryptHeader object.

#### Returns

a new GMimeAutocryptHeader object.

[transfer full]

### g_mime_autocrypt_header_new_from_string ()

    GMimeAutocryptHeader *
    g_mime_autocrypt_header_new_from_string
                                   (const char *string);

Creates a new GMimeAutocryptHeader object based on the value of an Autocrypt: header.

Note that this will not have an `effective_date` set, since the `effective_date` is derived from the Date: line in the same block of e-mail headers, but cannot be extracted from the raw Autocrypt: header itself.

#### Parameters

string | The raw string value of an Autocrypt header |

#### Returns

a new GMimeAutocryptHeader object, or `NULL` on error.

[transfer full]

### g_mime_autocrypt_header_get_address ()

    InternetAddressMailbox *
    g_mime_autocrypt_header_get_address (GMimeAutocryptHeader *ah);

Gets the internal address of the Autocrypt header, or `NULL` if not set.

#### Parameters

ah | a GMimeAutocryptHeader object |

#### Returns

the address associated with the Autocrypt header.

[transfer none]

### g_mime_autocrypt_header_set_address ()

    void
    g_mime_autocrypt_header_set_address (GMimeAutocryptHeader *ah,
                                         InternetAddressMailbox *address);

Set the address associated with the autocrypt_header.

#### Parameters

ah | a GMimeAutocryptHeader object |
address | a InternetAddressMailbox value |

### g_mime_autocrypt_header_set_address_from_string ()

    void
    g_mime_autocrypt_header_set_address_from_string
                                   (GMimeAutocryptHeader *ah,
                                    const char *address);

Set the address associated with the autocrypt_header.

#### Parameters

ah | a GMimeAutocryptHeader object |
address | a `NULL`-terminated string that is a raw e-mail address |

### g_mime_autocrypt_header_get_address_as_string ()

    const char *
    g_mime_autocrypt_header_get_address_as_string
                                   (GMimeAutocryptHeader *ah);

Gets the internal address of the Autocrypt header as a C string, or `NULL` if not set.

#### Parameters

ah | a GMimeAutocryptHeader object |

#### Returns

the address associated with the Autocrypt header.

[transfer none]

### g_mime_autocrypt_header_get_prefer_encrypt ()

    GMimeAutocryptPreferEncrypt
    g_mime_autocrypt_header_get_prefer_encrypt
                                   (GMimeAutocryptHeader *ah);

Gets the encryption preference stated by the Autocrypt header.

#### Parameters

ah | a GMimeAutocryptHeader object |

#### Returns

the encryption preference associated with the Autocrypt header

### g_mime_autocrypt_header_set_prefer_encrypt ()

    void
    g_mime_autocrypt_header_set_prefer_encrypt
                                   (GMimeAutocryptHeader *ah,
                                    GMimeAutocryptPreferEncrypt pref);

Set the encryption preference associated with the Autocrypt header.

#### Parameters

ah | a GMimeAutocryptHeader object |
pref | a GMimeAutocryptPreferEncrypt value |

### g_mime_autocrypt_header_get_keydata ()

    GBytes *
    g_mime_autocrypt_header_get_keydata (GMimeAutocryptHeader *ah);

Gets the raw keydata of the Autocrypt header, or `NULL` if not set.

#### Parameters

ah | a GMimeAutocryptHeader object |

#### Returns

the raw key data associated with the Autocrypt header.

[transfer none]

### g_mime_autocrypt_header_set_keydata ()

    void
    g_mime_autocrypt_header_set_keydata (GMimeAutocryptHeader *ah,
                                         GBytes *keydata);

Set the raw key data associated with the Autocrypt header.

#### Parameters

ah | a GMimeAutocryptHeader object |
keydata | a GBytes object |

### g_mime_autocrypt_header_get_effective_date ()

    GDateTime *
    g_mime_autocrypt_header_get_effective_date
                                   (GMimeAutocryptHeader *ah);

Gets the effective date of the Autocrypt header, or `NULL` if not set.

#### Parameters

ah | a GMimeAutocryptHeader object |

#### Returns

the effective date associated with the Autocrypt header.

[transfer none]

### g_mime_autocrypt_header_set_effective_date ()

    void
    g_mime_autocrypt_header_set_effective_date
                                   (GMimeAutocryptHeader *ah,
                                    GDateTime *effective_date);

Set the effective date associated with the Autocrypt header.

#### Parameters

ah | a GMimeAutocryptHeader object |
effective_date | a GDateTime object |

### g_mime_autocrypt_header_is_complete ()

    gboolean
    g_mime_autocrypt_header_is_complete (GMimeAutocryptHeader *ah);

When dealing with Autocrypt headers derived from a message, some sender addresses will not have a legitimate/complete header associated with them. When a given sender address has no complete header of a specific type, it should "reset" the state of the associated address.

#### Parameters

ah | a GMimeAutocryptHeader object |

#### Returns

`TRUE` if the header is complete, or `FALSE` if it is incomplete.

### g_mime_autocrypt_header_to_string ()

    char *
    g_mime_autocrypt_header_to_string (GMimeAutocryptHeader *ah,
                                       gboolean gossip);

Gets the string representation of the Autocrypt header, or `NULL` on error. For example, it might return:

prefer-encrypt=mutual; addr=bob@example.com; keydata=AAAB15BE...

If you are using this object to populate an Autocrypt-Gossip header, you should set `gossip` to `TRUE` (this will suppress inclusion of prefer-encrypt).

#### Parameters

ah | a GMimeAutocryptHeader object |
gossip | a gboolean, indicating whether this header is for use with gossip |

#### Returns

the string representation of the Autocrypt header.

[transfer full]

### g_mime_autocrypt_header_compare ()

    int
    g_mime_autocrypt_header_compare (GMimeAutocryptHeader *ah1,
                                     GMimeAutocryptHeader *ah2);

Compare two Autocrypt Headers. This is useful for comparison, as well as for sorting headers by:

- address

- effective_date

- keydata

- prefer_encrypt

#### Parameters

ah1 | a GMimeAutocryptHeader object |
ah2 | a GMimeAutocryptHeader object |

#### Returns

-1, 0, or 1 when `ah1` is less than, equal to, or greater than `ah2` .

### g_mime_autocrypt_header_clone ()

    void
    g_mime_autocrypt_header_clone (GMimeAutocryptHeader *dst,
                                   GMimeAutocryptHeader *src);

If address and type already match between `src` and `dst` , copy keydata, prefer_encrypt, effective_date from `src` to `dst` .

#### Parameters

dst | a GMimeAutocryptHeader object |
src | a GMimeAutocryptHeader object |

### g_mime_autocrypt_header_list_new ()

    GMimeAutocryptHeaderList *
    g_mime_autocrypt_header_list_new (void);

Creates a new GMimeAutocryptHeaderList object.

#### Returns

a new GMimeAutocryptHeaderList object.

[transfer full]

### g_mime_autocrypt_header_list_add_missing_addresses ()

    guint
    g_mime_autocrypt_header_list_add_missing_addresses
                                   (GMimeAutocryptHeaderList *list,
                                    InternetAddressList *addresses);

Adds a new incomplete GMimeAutocryptHeader object for each InternetAddressMailbox found in addresses.

#### Parameters

list | a GMimeAutocryptHeaderList object |
addresses | an InternetAddressList object |

#### Returns

the number of addresses added

### g_mime_autocrypt_header_list_add ()

    void
    g_mime_autocrypt_header_list_add (GMimeAutocryptHeaderList *list,
                                      GMimeAutocryptHeader *header);

Adds a the passed GMimeAutocryptHeader to the list.

#### Parameters

list | a GMimeAutocryptHeaderList object |
header | a GMimeAutocryptHeader object |

### g_mime_autocrypt_header_list_get_count ()

    guint
    g_mime_autocrypt_header_list_get_count
                                   (GMimeAutocryptHeaderList *list);

See how many Autocrypt headers are in the list.

#### Parameters

list | a GMimeAutocryptHeaderList object |

#### Returns

the number of available Autocrypt headers

### g_mime_autocrypt_header_list_get_header_at ()

    GMimeAutocryptHeader *
    g_mime_autocrypt_header_list_get_header_at
                                   (GMimeAutocryptHeaderList *list,
                                    guint index);

Get the Nth header in the list (returns `NULL` on error, or if `index` is out of bounds)

#### Parameters

list | a GMimeAutocryptHeaderList object |
index | an index into the list |

#### Returns

a pointer to the Nth header in the list.

[transfer none]

### g_mime_autocrypt_header_list_get_header_for_address ()

    GMimeAutocryptHeader *
    g_mime_autocrypt_header_list_get_header_for_address
                                   (GMimeAutocryptHeaderList *list,
                                    InternetAddressMailbox *mailbox);

Gets the Autocrypt header corresponding to the given `mailbox` .

#### Parameters

list | a GMimeAutocryptHeaderList object |
mailbox | an InternetAddressMailbox object |

#### Returns

a pointer to the header in the list which matches the requested address, or `NULL` if no such header exists in the list.

[transfer none]

### g_mime_autocrypt_header_list_remove_incomplete ()

    void
    g_mime_autocrypt_header_list_remove_incomplete
                                   (GMimeAutocryptHeaderList *list);

Remove all incomplete Autocrypt headers from the list.

#### Parameters

list | a GMimeAutocryptHeaderList object |

## Types and Values

### enum GMimeAutocryptPreferEncrypt

A description of the user's preference for encrypted messaging.

#### Members

GMIME_AUTOCRYPT_PREFER_ENCRYPT_NONE | No preference stated. |
GMIME_AUTOCRYPT_PREFER_ENCRYPT_MUTUAL | Please encrypt, if you also have this preference |

### struct GMimeAutocryptHeader

    struct GMimeAutocryptHeader {
    	GObject parent_object;

    	InternetAddressMailbox *address;
    	GMimeAutocryptPreferEncrypt prefer_encrypt;
    	GBytes *keydata;
    	GDateTime *effective_date;
    };

An object containing Autocrypt information about a given e-mail address, as derived from a message header.

See https://autocrypt.org/ for details and motivation.

#### Members

GObject `parent_object`; | parent GObject |
InternetAddressMailbox *`address`; | the InternetAddressMailbox associated with this Autocrypt header. |
GMimeAutocryptPreferEncrypt `prefer_encrypt`; | a GMimeAutocryptPreferEncrypt value (defaults to `GMIME_AUTOCRYPT_PREFER_ENCRYPT_NONE` ). |
GBytes *`keydata`; | the raw binary form of the encoded key. |
GDateTime *`effective_date`; | the date associated with the Autocrypt header in this message. |

### struct GMimeAutocryptHeaderList

    struct GMimeAutocryptHeaderList {
    	GObject parent_object;
    };

A list of Autocrypt headers, typically extracted from a GMimeMessage.

#### Members

GObject `parent_object`; | parent GObject |

## See Also

https://autocrypt.org