.TH xcb_get_property 3  "libxcb 1.14" "X Version 11" "XCB Requests"
.ad l
.SH NAME
xcb_get_property \- Gets a window property
.SH SYNOPSIS
.hy 0
.B #include <xcb/xproto.h>
.SS Request function
.HP
xcb_get_property_cookie_t \fBxcb_get_property\fP(xcb_connection_t\ *\fIconn\fP, uint8_t\ \fI_delete\fP, xcb_window_t\ \fIwindow\fP, xcb_atom_t\ \fIproperty\fP, xcb_atom_t\ \fItype\fP, uint32_t\ \fIlong_offset\fP, uint32_t\ \fIlong_length\fP);
.PP
.SS Reply datastructure
.nf
.sp
typedef struct xcb_get_property_reply_t {
    uint8_t    \fIresponse_type\fP;
    uint8_t    \fIformat\fP;
    uint16_t   \fIsequence\fP;
    uint32_t   \fIlength\fP;
    xcb_atom_t \fItype\fP;
    uint32_t   \fIbytes_after\fP;
    uint32_t   \fIvalue_len\fP;
    uint8_t    \fIpad0\fP[12];
} \fBxcb_get_property_reply_t\fP;
.fi
.SS Reply function
.HP
xcb_get_property_reply_t *\fBxcb_get_property_reply\fP(xcb_connection_t\ *\fIconn\fP, xcb_get_property_cookie_t\ \fIcookie\fP, xcb_generic_error_t\ **\fIe\fP);
.SS Reply accessors
.HP
void *\fBxcb_get_property_value\fP(const xcb_get_property_request_t *\fIreply\fP);
.HP
int \fBxcb_get_property_value_length\fP(const xcb_get_property_reply_t *\fIreply\fP);
.HP
xcb_generic_iterator_t \fBxcb_get_property_value_end\fP(const xcb_get_property_reply_t *\fIreply\fP);
.br
.hy 1
.SH REQUEST ARGUMENTS
.IP \fIconn\fP 1i
The XCB connection to X11.
.IP \fI_delete\fP 1i
Whether the property should actually be deleted. For deleting a property, the
specified \fItype\fP has to match the actual property type.
.IP \fIwindow\fP 1i
The window whose property you want to get.
.IP \fIproperty\fP 1i
The property you want to get (an atom).
.IP \fItype\fP 1i
The type of the property you want to get (an atom).
.IP \fIlong_offset\fP 1i
Specifies the offset (in 32-bit multiples) in the specified property where the
data is to be retrieved.
.IP \fIlong_length\fP 1i
Specifies how many 32-bit multiples of data should be retrieved (e.g. if you
set \fIlong_length\fP to 4, you will receive 16 bytes of data).
.SH REPLY FIELDS
.IP \fIresponse_type\fP 1i
The type of this reply, in this case \fIXCB_GET_PROPERTY\fP. This field is also present in the \fIxcb_generic_reply_t\fP and can be used to tell replies apart from each other.
.IP \fIsequence\fP 1i
The sequence number of the last request processed by the X11 server.
.IP \fIlength\fP 1i
The length of the reply, in words (a word is 4 bytes).
.IP \fIformat\fP 1i
Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or
32-bit quantities. Possible values are 8, 16, and 32. This information allows
the X server to correctly perform byte-swap operations as necessary.
.IP \fItype\fP 1i
The actual type of the property (an atom).
.IP \fIbytes_after\fP 1i
The number of bytes remaining to be read in the property if a partial read was
performed.
.IP \fIvalue_len\fP 1i
The length of value. You should use the corresponding accessor instead of this
field.
.SH DESCRIPTION
Gets the specified \fIproperty\fP from the specified \fIwindow\fP. Properties are for
example the window title (\fIWM_NAME\fP) or its minimum size (\fIWM_NORMAL_HINTS\fP).
Protocols such as EWMH also use properties - for example EWMH defines the
window title, encoded as UTF-8 string, in the \fI_NET_WM_NAME\fP property.

TODO: talk about \fItype\fP

TODO: talk about \fIdelete\fP

TODO: talk about the offset/length thing. what's a valid use case?
.SH RETURN VALUE
Returns an \fIxcb_get_property_cookie_t\fP. Errors have to be handled when calling the reply function \fIxcb_get_property_reply\fP.

If you want to handle errors in the event loop instead, use \fIxcb_get_property_unchecked\fP. See \fBxcb-requests(3)\fP for details.
.SH ERRORS
.IP \fIxcb_atom_error_t\fP 1i
\fIproperty\fP or \fItype\fP do not refer to a valid atom.
.IP \fIxcb_value_error_t\fP 1i
The specified \fIlong_offset\fP is beyond the actual property length (e.g. the
property has a length of 3 bytes and you are setting \fIlong_offset\fP to 1,
resulting in a byte offset of 4).
.IP \fIxcb_window_error_t\fP 1i
The specified \fIwindow\fP does not exist.
.SH EXAMPLE
.nf
.sp
/*
 * Prints the WM_NAME property of the window.
 *
 */
void my_example(xcb_connection_t *c, xcb_window_t window) {
    xcb_get_property_cookie_t cookie;
    xcb_get_property_reply_t *reply;

    /* These atoms are predefined in the X11 protocol. */
    xcb_atom_t property = XCB_ATOM_WM_NAME;
    xcb_atom_t type = XCB_ATOM_STRING;

    // TODO: a reasonable long_length for WM_NAME?
    cookie = xcb_get_property(c, 0, window, property, type, 0, 0);
    if ((reply = xcb_get_property_reply(c, cookie, NULL))) {
        int len = xcb_get_property_value_length(reply);
        if (len == 0) {
            printf("TODO\\n");
            free(reply);
            return;
        }
        printf("WM_NAME is %.*s\\n", len,
               (char*)xcb_get_property_value(reply));
    }
    free(reply);
}
.fi
.SH SEE ALSO
.BR xcb-requests (3),
.BR xcb-examples (3),
.BR xcb_intern_atom (3),
.BR xprop (1)
.SH AUTHOR
Generated from xproto.xml. Contact xcb@lists.freedesktop.org for corrections and improvements.