TpTLSCertificate: telepathy-glib API Reference Manual

## TpTLSCertificate TpTLSCertificate — proxy object for a server or peer's TLS certificate |

## Functions

void | tp_tls_certificate_init_known_interfaces ()
TpTLSCertificate * | tp_tls_certificate_new ()
TpTLSCertificateRejection * | tp_tls_certificate_get_rejection ()
TpTLSCertificateRejection * | tp_tls_certificate_get_nth_rejection ()
void | tp_tls_certificate_accept_async ()
gboolean | tp_tls_certificate_accept_finish ()
void | tp_tls_certificate_add_rejection ()
void | tp_tls_certificate_reject_async ()
gboolean | tp_tls_certificate_reject_finish ()
const gchar * | tp_tls_certificate_get_cert_type ()
GPtrArray * | tp_tls_certificate_get_cert_data ()
TpTLSCertificateState | tp_tls_certificate_get_state ()

## Properties

GPtrArray * | cert-data | Read
gchar * | cert-type | Read
TpProxy * | parent | Read / Write / Construct Only
guint | state | Read

## Types and Values

struct | TpTLSCertificate
#define | TP_TLS_CERTIFICATE_FEATURE_CORE

## Object Hierarchy

        GObject
        ╰── TpProxy
            ╰── TpTLSCertificate

## Includes

    #include <telepathy-glib/telepathy-glib.h>

## Description

TpTLSCertificate is a TpProxy subclass for TLSCertificate objects, used in Channel.Type.ServerTLSConnection.

## Functions

### tp_tls_certificate_init_known_interfaces ()

    void
    tp_tls_certificate_init_known_interfaces
                                   (void);

Ensure that the known interfaces for TpTLSCertificate have been set up. This is done automatically when necessary, but for correct overriding of library interfaces by local extensions, you should call this function before calling `tp_proxy_or_subclass_hook_on_interface_add()` with first argument `TP_TYPE_TLS_CERTIFICATE`.

Since: 0.19.0

### tp_tls_certificate_new ()

    TpTLSCertificate *
    tp_tls_certificate_new (TpProxy *conn_or_chan,
                            const gchar *object_path,
                            GError **error);

#### Parameters

conn_or_chan | a TpConnection or TpChannel parent for this object, whose invalidation will also result in invalidation of the returned object |
object_path | the object path of this TLS certificate |
error | a GError used to return an error if `NULL` is returned, or `NULL` |

#### Returns

a new TLS certificate proxy. Prepare the feature `TP_TLS_CERTIFICATE_FEATURE_CORE` to make it useful.

[transfer full]

Since: 0.19.0

### tp_tls_certificate_get_rejection ()

    TpTLSCertificateRejection *
    tp_tls_certificate_get_rejection (TpTLSCertificate *self);

If this certificate has been rejected, return a TpTLSCertificateRejection indicating the first rejection reason (by convention, the most important).

If you want to list all the things that are wrong with the certificate (for instance, it might be self-signed and also have expired) you can call `tp_tls_certificate_get_nth_rejection()`, increasing `n` until it returns `NULL`.

#### Parameters

self | a TLS certificate |

#### Returns

a TpTLSCertificateRejection, or `NULL`.

[transfer none][allow-none]

Since: 0.19.0

### tp_tls_certificate_get_nth_rejection ()

    TpTLSCertificateRejection *
    tp_tls_certificate_get_nth_rejection (TpTLSCertificate *self,
                                          guint n);

If this certificate has been rejected and `n` is less than the number of rejection reasons, return a TpTLSCertificateRejection representing the `n` th rejection reason (starting from 0).

With `n` == 0 this is equivalent to `tp_tls_certificate_get_rejection()`.

#### Parameters

self | a TLS certificate |
n | the rejection reason to return; if 0, return the same thing as `tp_tls_certificate_get_detailed_rejection()` |

#### Returns

a TpTLSCertificateRejection, or `NULL`.

[transfer none][allow-none]

Since: 0.19.0

### tp_tls_certificate_accept_async ()

    void
    tp_tls_certificate_accept_async (TpTLSCertificate *self,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Accept this certificate, asynchronously. In or after `callback` , you may call `tp_tls_certificate_accept_finish()` to check the result.

“:state” will also be emitted when the connection manager signals that the certificate has been accepted.

#### Parameters

self | a TLS certificate |
callback | called on success or failure |
user_data | user data for the callback |

Since: 0.19.0

### tp_tls_certificate_accept_finish ()

    gboolean
    tp_tls_certificate_accept_finish (TpTLSCertificate *self,
                                      GAsyncResult *result,
                                      GError **error);

Check the result of `tp_tls_certificate_accept_async()`.

#### Parameters

self | a TLS certificate |
result | the result passed to the callback by `tp_tls_certificate_accept_async()` |
error | used to raise an error if `FALSE` is returned |

#### Returns

`TRUE` if acceptance was successful

Since: 0.19.0

### tp_tls_certificate_add_rejection ()

    void
    tp_tls_certificate_add_rejection (TpTLSCertificate *self,
                                      TpTLSCertificateRejectReason reason,
                                      const gchar *dbus_error,
                                      GVariant *details);

Add a pending reason for rejection. The first call to this method is considered "most important". After calling this method as many times as are required, call `tp_tls_certificate_reject_async()` to reject the certificate.

If `details` is a floating reference (see `g_variant_ref_sink()`), ownership of `details` is taken by this function. This means you can pass the result of `g_variant_new()` or `g_variant_new_parsed()` directly to this function without additional reference-count management.

#### Parameters

self | a TLS certificate |
reason | the reason for rejection |
dbus_error | a D-Bus error name such as `TP_ERROR_STR_CERT_REVOKED`, or `NULL` to derive one from `reason` |
details | a variant of type `G_VARIANT_TYPE_VARDICT` containing the details of the rejection, or `NULL`. | [transfer none][allow-none]

Since: 0.19.0

### tp_tls_certificate_reject_async ()

    void
    tp_tls_certificate_reject_async (TpTLSCertificate *self,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Reject this certificate, asynchronously.

Before calling this method, you must call `tp_tls_certificate_add_rejection()` at least once, to set the reason(s) for rejection (for instance, a certificate might be both self-signed and expired).

In or after `callback` , you may call `tp_tls_certificate_reject_finish()` to check the result.

“:state” will also be emitted when the connection manager signals that the certificate has been rejected.

#### Parameters

self | a TLS certificate |
callback | called on success or failure |
user_data | user data for the callback |

Since: 0.19.0

### tp_tls_certificate_reject_finish ()

    gboolean
    tp_tls_certificate_reject_finish (TpTLSCertificate *self,
                                      GAsyncResult *result,
                                      GError **error);

Check the result of `tp_tls_certificate_reject_async()`.

#### Parameters

self | a TLS certificate |
result | the result passed to the callback by `tp_tls_certificate_reject_async()` |
error | used to raise an error if `FALSE` is returned |

#### Returns

`TRUE` if rejection was successful

Since: 0.19.0

### tp_tls_certificate_get_cert_type ()

    const gchar *
    tp_tls_certificate_get_cert_type (TpTLSCertificate *self);

Return the “cert-type” property

#### Parameters

self | a TpTLSCertificate |

#### Returns

the value of “cert-type” property

Since: 0.19.0

### tp_tls_certificate_get_cert_data ()

    GPtrArray *
    tp_tls_certificate_get_cert_data (TpTLSCertificate *self);

Return the “cert-data” property

#### Parameters

self | a TpTLSCertificate |

#### Returns

the value of “cert-data” property.

[transfer none][type GLib.PtrArray][element-type GLib.Bytes]

Since: 0.19.0

### tp_tls_certificate_get_state ()

    TpTLSCertificateState
    tp_tls_certificate_get_state (TpTLSCertificate *self);

Return the “state” property

#### Parameters

self | a TpTLSCertificate |

#### Returns

the value of “state” property

Since: 0.19.0

## Types and Values

### struct TpTLSCertificate

    struct TpTLSCertificate;

A TpProxy subclass representing a server or peer's TLS certificate being presented for acceptance/rejection.

Since: 0.19.0

### TP_TLS_CERTIFICATE_FEATURE_CORE

    #define             TP_TLS_CERTIFICATE_FEATURE_CORE

Expands to a call to a function that returns a quark representing the core functionality of a TpTLSCertificate.

When this feature is prepared, the basic properties of the object have been retrieved and are available for use:

- “cert-type”
- “cert-data”
- “state”

In addition, “:state” will be emitted if the state changes.

One can ask for a feature to be prepared using the `tp_proxy_prepare_async()` function, and waiting for it to callback.

Since: 0.19.0

## Property Details

### The `“cert-data”` property

      “cert-data”                GPtrArray *

The raw data of the certificate or certificate chain, represented as a GPtrArray of GBytes. It should be interpreted according to “cert-type”.

The first certificate in this array is the server's certificate, followed by its issuer, followed by the issuer's issuer and so on.

For "x509" certificates, each certificate is an X.509 certificate in binary (DER) format.

For "pgp" certificates, each certificate is a binary OpenPGP key.

Owner: TpTLSCertificate

Flags: Read

Since: 0.19.0

### The `“cert-type”` property

      “cert-type”                gchar *

The type of the certificate, typically either "x509" or "pgp".

Owner: TpTLSCertificate

Flags: Read

Default value: NULL

Since: 0.19.0

### The `“parent”` property

      “parent”                   TpProxy *

A TpConnection or TpChannel which owns this TLS certificate. If the parent object is invalidated, the certificate is also invalidated, and this property is set to `NULL`.

Owner: TpTLSCertificate

Flags: Read / Write / Construct Only

Since: 0.19.0

### The `“state”` property

      “state”                    guint

The state of this TLS certificate as a TpTLSCertificateState, initially `TP_TLS_CERTIFICATE_STATE_PENDING`.

“:state” will be emitted when this changes.

Owner: TpTLSCertificate

Flags: Read

Allowed values: <= 2

Default value: 0

Since: 0.19.0