DhLink: Devhelp Reference Manual

## DhLink DhLink — A link inside a DhBook |

## Functions

DhLink * | dh_link_new_book ()
DhLink * | dh_link_new ()
DhLink * | dh_link_ref ()
void | dh_link_unref ()
DhLinkType | dh_link_get_link_type ()
DhLinkFlags | dh_link_get_flags ()
void | dh_link_set_flags ()
const gchar * | dh_link_get_name ()
gboolean | dh_link_match_relative_url ()
gboolean | dh_link_belongs_to_page ()
gchar * | dh_link_get_uri ()
const gchar * | dh_link_get_book_title ()
const gchar * | dh_link_get_book_id ()
gint | dh_link_compare ()
const gchar * | dh_link_type_to_string ()

## Types and Values

| DhLink
enum | DhLinkType
enum | DhLinkFlags

## Object Hierarchy

        GBoxed
        ╰── DhLink
        GEnum
        ╰── DhLinkType
        GFlags
        ╰── DhLinkFlags

## Includes

    #include <devhelp/devhelp.h>

## Description

A DhLink represents a link to an HTML page or somewhere inside a page (with an anchor) that is inside a DhBook. The link can point to a specific symbol, or a page, or the top-level page of the DhBook.

A DhLink has a type that can be retrieved with `dh_link_get_link_type()`.

There is exactly one DhLink of type `DH_LINK_TYPE_BOOK` per DhBook object.

## Functions

### dh_link_new_book ()

    DhLink *
    dh_link_new_book (const gchar *base_path,
                      const gchar *book_id,
                      const gchar *book_title,
                      const gchar *relative_url);

#### Parameters

base_path | the base path for the book. |
book_id | the book ID. |
book_title | the name of the link. |
relative_url | the URL relative to the book `base_path` . Can contain an anchor. Usually the index.html page. |

#### Returns

a new DhLink of type `DH_LINK_TYPE_BOOK`.

Since: 3.28

### dh_link_new ()

    DhLink *
    dh_link_new (DhLinkType type,
                 DhLink *book_link,
                 const gchar *name,
                 const gchar *relative_url);

#### Parameters

type | the DhLinkType. Must be different than `DH_LINK_TYPE_BOOK`. |
book_link | the DhLink of type `DH_LINK_TYPE_BOOK` for the book that the link is contained in. |
name | the name of the link. |
relative_url | the URL relative to the book base path. Can contain an anchor. |

#### Returns

a new DhLink.

### dh_link_ref ()

    DhLink *
    dh_link_ref (DhLink *link);

Increases the reference count of `link` .

Not thread-safe.

#### Parameters

link | a DhLink. |

#### Returns

the `link` .

[transfer full]

### dh_link_unref ()

    void
    dh_link_unref (DhLink *link);

Decreases the reference count of `link` .

Not thread-safe.

#### Parameters

link | a DhLink. |

### dh_link_get_link_type ()

    DhLinkType
    dh_link_get_link_type (DhLink *link);

#### Parameters

link | a DhLink. |

#### Returns

the DhLinkType of `link` .

### dh_link_get_flags ()

    DhLinkFlags
    dh_link_get_flags (DhLink *link);

#### Parameters

link | a DhLink. |

#### Returns

the DhLinkFlags of `link` .

### dh_link_set_flags ()

    void
    dh_link_set_flags (DhLink *link,
                       DhLinkFlags flags);

Sets the flags of the link.

#### Parameters

link | a DhLink. |
flags | the new flags of the link. |

### dh_link_get_name ()

    const gchar *
    dh_link_get_name (DhLink *link);

#### Parameters

link | a DhLink. |

#### Returns

the name of the `link` . For a link of type `DH_LINK_TYPE_BOOK`, returns the book title.

### dh_link_match_relative_url ()

    gboolean
    dh_link_match_relative_url (DhLink *link,
                                const gchar *relative_url);

#### Parameters

link | a DhLink. |
relative_url | an URL relative to the book base path. Can contain an anchor. |

#### Returns

whether the relative URL of `link` matches with `relative_url` . There is a special case for the index.html page, it can also match the empty string.

Since: 3.28

### dh_link_belongs_to_page ()

    gboolean
    dh_link_belongs_to_page (DhLink *link,
                             const gchar *page_id);

This function permits to know if `link` belongs to a certain page.

`page_id` is usually the HTML filename without the `.html` extension. More generally, `page_id` must be a relative URL (relative to the book base path), without the anchor nor the file extension.

For example if `link` has the relative URL `"DhLink.html#dh-link-ref"`, then this function will return `TRUE` if the `page_id` is `"DhLink"`.

#### Parameters

link | a DhLink. |
page_id | a page ID, i.e. the filename without its extension. |

#### Returns

whether `link` belongs to `page_id` .

Since: 3.28

### dh_link_get_uri ()

    gchar *
    dh_link_get_uri (DhLink *link);

Gets the `link` URI, by concateneting the book base path with the `link` relative URL.

#### Parameters

link | a DhLink. |

#### Returns

the `link` URI, or `NULL` if getting the URI failed. Free with `g_free()` when no longer needed.

[nullable]

### dh_link_get_book_title ()

    const gchar *
    dh_link_get_book_title (DhLink *link);

#### Parameters

link | a DhLink. |

#### Returns

the title of the book that the `link` is contained in.

### dh_link_get_book_id ()

    const gchar *
    dh_link_get_book_id (DhLink *link);

#### Parameters

link | a DhLink. |

#### Returns

the ID of the book that the `link` is contained in.

### dh_link_compare ()

    gint
    dh_link_compare (gconstpointer a,
                     gconstpointer b);

Compares the links `a` and `b` . This function is used to determine in which order the links should be displayed.

#### Parameters

a | a DhLink. | [type DhLink]
b | a DhLink. | [type DhLink]

#### Returns

an integer less than zero if `a` should appear before `b` ; zero if there are no preferences; an integer greater than zero if `b` should appear before `a` .

### dh_link_type_to_string ()

    const gchar *
    dh_link_type_to_string (DhLinkType link_type);

#### Parameters

link_type | a DhLinkType. |

#### Returns

a string representation of the DhLinkType, translated in the current language.

## Types and Values

### DhLink

    typedef struct _DhLink DhLink;

### enum DhLinkType

The type of the content the link points to.

#### Members

DH_LINK_TYPE_BOOK | The top-level page of a DhBook. |
DH_LINK_TYPE_PAGE | A page. |
DH_LINK_TYPE_KEYWORD | Another kind of keyword. |
DH_LINK_TYPE_FUNCTION | A function keyword. |
DH_LINK_TYPE_STRUCT | A struct keyword. |
DH_LINK_TYPE_MACRO | A macro keyword. |
DH_LINK_TYPE_ENUM | An enum keyword. |
DH_LINK_TYPE_TYPEDEF | A typedef keyword. |
DH_LINK_TYPE_PROPERTY | A property keyword. |
DH_LINK_TYPE_SIGNAL | A signal keyword. |

### enum DhLinkFlags

#### Members

DH_LINK_FLAGS_NONE | No flags set. |
DH_LINK_FLAGS_DEPRECATED | The symbol that the link points to is deprecated. |