## TpTLSCertificate

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

## Synopsis

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

                        TpTLSCertificate;
    void                tp_tls_certificate_init_known_interfaces
                                                            (void);
    TpTLSCertificate *  tp_tls_certificate_new              (TpProxy *conn_or_chan,
                                                             const gchar *object_path,
                                                             GError **error);
    #define             TP_TLS_CERTIFICATE_FEATURE_CORE
    TpTLSCertificateRejection * tp_tls_certificate_get_rejection
                                                            (TpTLSCertificate *self);
    TpTLSCertificateRejection * tp_tls_certificate_get_nth_rejection
                                                            (TpTLSCertificate *self,
                                                             guint n);
    void                tp_tls_certificate_accept_async     (TpTLSCertificate *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_tls_certificate_accept_finish    (TpTLSCertificate *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    void                tp_tls_certificate_add_rejection    (TpTLSCertificate *self,
                                                             TpTLSCertificateRejectReason reason,
                                                             const gchar *dbus_error,
                                                             GVariant *details);
    void                tp_tls_certificate_reject_async     (TpTLSCertificate *self,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            tp_tls_certificate_reject_finish    (TpTLSCertificate *self,
                                                             GAsyncResult *result,
                                                             GError **error);
    const gchar *       tp_tls_certificate_get_cert_type    (TpTLSCertificate *self);
    GPtrArray *         tp_tls_certificate_get_cert_data    (TpTLSCertificate *self);
    TpTLSCertificateState tp_tls_certificate_get_state      (TpTLSCertificate *self);

## Object Hierarchy

      GObject
       +----TpProxy
             +----TpTLSCertificate

## Properties

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

## Description

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

## Details

### TpTLSCertificate

    typedef struct _TpTLSCertificate TpTLSCertificate;

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

Since 0.19.0

### 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);

`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_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

### 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`.

`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()`.

`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.

`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()`.

`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.

`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.

`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()`.

`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

`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

`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

`self` : | a TpTLSCertificate
Returns : | the value of "state" property

Since 0.19.0

## Property Details

### The `"cert-data"` property

      "cert-data"                GPtrArray*            : Read

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.

Since 0.19.0

### The `"cert-type"` property

      "cert-type"                gchar*                : Read

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

Default value: NULL

Since 0.19.0

### The `"parent"` property

      "parent"                   TpProxy*              : Read / Write / Construct Only

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`.

Since 0.19.0

### The `"state"` property

      "state"                    guint                 : Read

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

":state" will be emitted when this changes.

Allowed values: <= 2

Default value: 0

Since 0.19.0