_dbus_bindings/string.c

   1 /* Simple D-Bus types: ObjectPath and other string types.
   2  *
   3  * Copyright (C) 2006-2007 Collabora Ltd. <http://www.collabora.co.uk/>
   4  *
   5  * Permission is hereby granted, free of charge, to any person
   6  * obtaining a copy of this software and associated documentation
   7  * files (the "Software"), to deal in the Software without
   8  * restriction, including without limitation the rights to use, copy,
   9  * modify, merge, publish, distribute, sublicense, and/or sell copies
  10  * of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be
  14  * included in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  20  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  21  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  23  * DEALINGS IN THE SOFTWARE.
  24  */
  25
  26 #include "types-internal.h"
  27 #include <structmember.h>
  28
  29 /* UTF-8 string representation ====================================== */
  30
  31 PyDoc_STRVAR(UTF8String_tp_doc,
  32 "A string represented using UTF-8 - a subtype of `str`.\n"
  33 "\n"
  34 "All strings on D-Bus are required to be valid Unicode; in the \"wire\n"
  35 "protocol\" they're transported as UTF-8.\n"
  36 "\n"
  37 "By default, when byte arrays are converted from D-Bus to Python, they\n"
  38 "come out as a `dbus.String`, which is a subtype of `unicode`.\n"
  39 "If you prefer to get UTF-8 strings (as instances of this class) or you\n"
  40 "want to avoid the conversion overhead of going from UTF-8 to Python's\n"
  41 "internal Unicode representation, you can pass the ``utf8_strings=True``\n"
  42 "keyword argument to any of these methods:\n"
  43 "\n"
  44 "* any D-Bus method proxy, or ``connect_to_signal``, on the objects returned\n"
  45 "  by `Bus.get_object`\n"
  46 "* any D-Bus method on a `dbus.Interface`\n"
  47 "* `dbus.Interface.connect_to_signal`\n"
  48 "* `Bus.add_signal_receiver`\n"
  49 "\n"
  50 "\n"
  51 "Constructor::\n"
  52 "\n"
  53 "    dbus.UTF8String(value: str or unicode[, variant_level: int]) -> UTF8String\n"
  54 "\n"
  55 "If value is a str object it must be valid UTF-8.\n"
  56 "\n"
  57 "variant_level must be non-negative; the default is 0.\n"
  58 "\n"
  59 ":IVariables:\n"
  60 "  `variant_level` : int\n"
  61 "    Indicates how many nested Variant containers this object\n"
  62 "    is contained in: if a message's wire format has a variant containing a\n"
  63 "    variant containing a string, this is represented in Python by a\n"
  64 "    String or UTF8String with variant_level==2.\n"
  65 ":Since: 0.80 (in older versions, use dbus.String)\n"
  66 );
  67
  68 static PyObject *
  69 UTF8String_tp_new(PyTypeObject *cls, PyObject *args, PyObject *kwargs)
  70 {
  71     const char *str = NULL;
  72     long variantness = 0;
  73     static char *argnames[] = {"value", "variant_level", NULL};
  74     PyObject *unicode;
  75
  76     if (!PyArg_ParseTupleAndKeywords(args, kwargs, "s|l:__new__", argnames,
  77                                      &str, &variantness)) return NULL;
  78     unicode = PyUnicode_DecodeUTF8(str, strlen(str), NULL);
  79     if (!unicode) return NULL;
  80     Py_DECREF(unicode);
  81     return (DBusPyStrBase_Type.tp_new)(cls, args, kwargs);
  82 }
  83
  84 PyTypeObject DBusPyUTF8String_Type = {
  85     PyObject_HEAD_INIT(DEFERRED_ADDRESS(&PyType_Type))
  86     0,
  87     "dbus.UTF8String",
  88     0,
  89     0,
  90     0,                                      /* tp_dealloc */
  91     0,                                      /* tp_print */
  92     0,                                      /* tp_getattr */
  93     0,                                      /* tp_setattr */
  94     0,                                      /* tp_compare */
  95     0,                                      /* tp_repr */
  96     0,                                      /* tp_as_number */
  97     0,                                      /* tp_as_sequence */
  98     0,                                      /* tp_as_mapping */
  99     0,                                      /* tp_hash */
 100     0,                                      /* tp_call */
 101     0,                                      /* tp_str */
 102     0,                                      /* tp_getattro */
 103     0,                                      /* tp_setattro */
 104     0,                                      /* tp_as_buffer */
 105     Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
 106     UTF8String_tp_doc,                      /* tp_doc */
 107     0,                                      /* tp_traverse */
 108     0,                                      /* tp_clear */
 109     0,                                      /* tp_richcompare */
 110     0,                                      /* tp_weaklistoffset */
 111     0,                                      /* tp_iter */
 112     0,                                      /* tp_iternext */
 113     0,                                      /* tp_methods */
 114     0,                                      /* tp_members */
 115     0,                                      /* tp_getset */
 116     DEFERRED_ADDRESS(&DBusPyStrBase_Type),   /* tp_base */
 117     0,                                      /* tp_dict */
 118     0,                                      /* tp_descr_get */
 119     0,                                      /* tp_descr_set */
 120     0,                                      /* tp_dictoffset */
 121     0,                                      /* tp_init */
 122     0,                                      /* tp_alloc */
 123     UTF8String_tp_new,                      /* tp_new */
 124 };
 125
 126 /* Object path ====================================================== */
 127
 128 PyDoc_STRVAR(ObjectPath_tp_doc,
 129 "A D-Bus object path, such as '/com/example/MyApp/Documents/abc'.\n"
 130 "\n"
 131 "ObjectPath is a subtype of str, and object-paths behave like strings.\n"
 132 "\n"
 133 "Constructor::\n"
 134 "\n"
 135 "    dbus.ObjectPath(path: str, variant_level: int) -> ObjectPath\n"
 136 "\n"
 137 "path must be an ASCII string following the syntax of object paths.\n"
 138 "variant_level must be non-negative; the default is 0.\n"
 139 "\n"
 140 ":IVariables:\n"
 141 "  `variant_level` : int\n"
 142 "    Indicates how many nested Variant containers this object\n"
 143 "    is contained in: if a message's wire format has a variant containing a\n"
 144 "    variant containing an object path, this is represented in Python by an\n"
 145 "    ObjectPath with variant_level==2.\n"
 146 );
 147
 148 static PyObject *
 149 ObjectPath_tp_new(PyTypeObject *cls, PyObject *args, PyObject *kwargs)
 150 {
 151     const char *str = NULL;
 152     long variantness = 0;
 153     static char *argnames[] = {"object_path", "variant_level", NULL};
 154
 155     if (!PyArg_ParseTupleAndKeywords(args, kwargs, "s|l:__new__", argnames,
 156                                      &str, &variantness)) return NULL;
 157     if (!dbus_py_validate_object_path(str)) {
 158         return NULL;
 159     }
 160     return (DBusPyStrBase_Type.tp_new)(cls, args, kwargs);
 161 }
 162
 163 PyTypeObject DBusPyObjectPath_Type = {
 164     PyObject_HEAD_INIT(DEFERRED_ADDRESS(&PyType_Type))
 165     0,
 166     "dbus.ObjectPath",
 167     0,
 168     0,
 169     0,                                      /* tp_dealloc */
 170     0,                                      /* tp_print */
 171     0,                                      /* tp_getattr */
 172     0,                                      /* tp_setattr */
 173     0,                                      /* tp_compare */
 174     0,                                      /* tp_repr */
 175     0,                                      /* tp_as_number */
 176     0,                                      /* tp_as_sequence */
 177     0,                                      /* tp_as_mapping */
 178     0,                                      /* tp_hash */
 179     0,                                      /* tp_call */
 180     0,                                      /* tp_str */
 181     0,                                      /* tp_getattro */
 182     0,                                      /* tp_setattro */
 183     0,                                      /* tp_as_buffer */
 184     Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
 185     ObjectPath_tp_doc,                      /* tp_doc */
 186     0,                                      /* tp_traverse */
 187     0,                                      /* tp_clear */
 188     0,                                      /* tp_richcompare */
 189     0,                                      /* tp_weaklistoffset */
 190     0,                                      /* tp_iter */
 191     0,                                      /* tp_iternext */
 192     0,                                      /* tp_methods */
 193     0,                                      /* tp_members */
 194     0,                                      /* tp_getset */
 195     DEFERRED_ADDRESS(&DBusPyStrBase_Type),   /* tp_base */
 196     0,                                      /* tp_dict */
 197     0,                                      /* tp_descr_get */
 198     0,                                      /* tp_descr_set */
 199     0,                                      /* tp_dictoffset */
 200     0,                                      /* tp_init */
 201     0,                                      /* tp_alloc */
 202     ObjectPath_tp_new,                      /* tp_new */
 203 };
 204
 205 /* Unicode string representation ==================================== */
 206
 207 PyDoc_STRVAR(String_tp_doc,
 208 "A string represented using Unicode - a subtype of `unicode`.\n"
 209 "\n"
 210 "All strings on D-Bus are required to be valid Unicode; in the \"wire\n"
 211 "protocol\" they're transported as UTF-8.\n"
 212 "\n"
 213 "By default, when strings are converted from D-Bus to Python, they\n"
 214 "come out as this class. If you prefer to get UTF-8 strings (as instances\n"
 215 "of a subtype of `str`) or you want to avoid the conversion overhead of\n"
 216 "going from UTF-8 to Python's internal Unicode representation, see the\n"
 217 "documentation for `dbus.UTF8String`.\n"
 218 "\n"
 219 "Constructor::\n"
 220 "\n"
 221 "    String(value: str or unicode[, variant_level: int]) -> String\n"
 222 "\n"
 223 "variant_level must be non-negative; the default is 0.\n"
 224 "\n"
 225 ":IVariables:\n"
 226 "  `variant_level` : int\n"
 227 "    Indicates how many nested Variant containers this object\n"
 228 "    is contained in: if a message's wire format has a variant containing a\n"
 229 "    variant containing a string, this is represented in Python by a\n"
 230 "    String or UTF8String with variant_level==2.\n"
 231 );
 232
 233 static PyMemberDef String_tp_members[] = {
 234     {"variant_level", T_LONG, offsetof(DBusPyString, variant_level),
 235      READONLY,
 236      "The number of nested variants wrapping the real data. "
 237      "0 if not in a variant"},
 238     {NULL},
 239 };
 240
 241 static PyObject *
 242 String_tp_new(PyTypeObject *cls, PyObject *args, PyObject *kwargs)
 243 {
 244     PyObject *self;
 245     long variantness = 0;
 246     static char *argnames[] = {"variant_level", NULL};
 247
 248     if (PyTuple_Size(args) > 1) {
 249         PyErr_SetString(PyExc_TypeError,
 250                         "__new__ takes at most one positional parameter");
 251         return NULL;
 252     }
 253     if (!PyArg_ParseTupleAndKeywords(dbus_py_empty_tuple, kwargs,
 254                                      "|l:__new__", argnames,
 255                                      &variantness)) return NULL;
 256     if (variantness < 0) {
 257         PyErr_SetString(PyExc_ValueError,
 258                         "variant_level must be non-negative");
 259         return NULL;
 260     }
 261     self = (PyUnicode_Type.tp_new)(cls, args, NULL);
 262     if (self) {
 263         ((DBusPyString *)self)->variant_level = variantness;
 264     }
 265     return self;
 266 }
 267
 268 static PyObject *
 269 String_tp_repr(PyObject *self)
 270 {
 271     PyObject *parent_repr = (PyUnicode_Type.tp_repr)(self);
 272     PyObject *my_repr;
 273
 274     if (!parent_repr) {
 275         return NULL;
 276     }
 277     if (((DBusPyString *)self)->variant_level > 0) {
 278         my_repr = PyString_FromFormat("%s(%s, variant_level=%ld)",
 279                                       self->ob_type->tp_name,
 280                                       PyString_AS_STRING(parent_repr),
 281                                       ((DBusPyString *)self)->variant_level);
 282     }
 283     else {
 284         my_repr = PyString_FromFormat("%s(%s)", self->ob_type->tp_name,
 285                                       PyString_AS_STRING(parent_repr));
 286     }
 287     /* whether my_repr is NULL or not: */
 288     Py_DECREF(parent_repr);
 289     return my_repr;
 290 }
 291
 292 PyTypeObject DBusPyString_Type = {
 293     PyObject_HEAD_INIT(DEFERRED_ADDRESS(&PyType_Type))
 294     0,
 295     "dbus.String",
 296     sizeof(DBusPyString),
 297     0,
 298     0,                                      /* tp_dealloc */
 299     0,                                      /* tp_print */
 300     0,                                      /* tp_getattr */
 301     0,                                      /* tp_setattr */
 302     0,                                      /* tp_compare */
 303     String_tp_repr,                         /* tp_repr */
 304     0,                                      /* tp_as_number */
 305     0,                                      /* tp_as_sequence */
 306     0,                                      /* tp_as_mapping */
 307     0,                                      /* tp_hash */
 308     0,                                      /* tp_call */
 309     0,                                      /* tp_str */
 310     PyObject_GenericGetAttr,                /* tp_getattro */
 311     dbus_py_immutable_setattro,                /* tp_setattro */
 312     0,                                      /* tp_as_buffer */
 313     Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
 314     String_tp_doc,                          /* tp_doc */
 315     0,                                      /* tp_traverse */
 316     0,                                      /* tp_clear */
 317     0,                                      /* tp_richcompare */
 318     0,                                      /* tp_weaklistoffset */
 319     0,                                      /* tp_iter */
 320     0,                                      /* tp_iternext */
 321     0,                                      /* tp_methods */
 322     String_tp_members,                      /* tp_members */
 323     0,                                      /* tp_getset */
 324     DEFERRED_ADDRESS(&PyUnicode_Type),      /* tp_base */
 325     0,                                      /* tp_dict */
 326     0,                                      /* tp_descr_get */
 327     0,                                      /* tp_descr_set */
 328     0,                                      /* tp_dictoffset */
 329     0,                                      /* tp_init */
 330     0,                                      /* tp_alloc */
 331     String_tp_new,                          /* tp_new */
 332 };
 333
 334 dbus_bool_t
 335 dbus_py_init_string_types(void)
 336 {
 337     /* don't need to do strange contortions for unicode, since it's not a
 338      * "variable-size" object (it has a pointer to its data instead)
 339      */
 340     if (PyUnicode_Type.tp_itemsize != 0) {
 341         fprintf(stderr, "dbus-python is not compatible with this version of "
 342                 "Python (unicode objects are assumed to be fixed-size)");
 343         return 0;
 344     }
 345     DBusPyString_Type.tp_base = &PyUnicode_Type;
 346     if (PyType_Ready(&DBusPyString_Type) < 0) return 0;
 347     DBusPyString_Type.tp_print = NULL;
 348
 349     DBusPyUTF8String_Type.tp_base = &DBusPyStrBase_Type;
 350     if (PyType_Ready(&DBusPyUTF8String_Type) < 0) return 0;
 351     DBusPyUTF8String_Type.tp_print = NULL;
 352
 353     DBusPyObjectPath_Type.tp_base = &DBusPyStrBase_Type;
 354     if (PyType_Ready(&DBusPyObjectPath_Type) < 0) return 0;
 355     DBusPyObjectPath_Type.tp_print = NULL;
 356
 357     DBusPyBoolean_Type.tp_base = &DBusPyIntBase_Type;
 358     if (PyType_Ready(&DBusPyBoolean_Type) < 0) return 0;
 359     DBusPyBoolean_Type.tp_print = NULL;
 360
 361     return 1;
 362 }
 363
 364 dbus_bool_t
 365 dbus_py_insert_string_types(PyObject *this_module)
 366 {
 367     Py_INCREF(&DBusPyObjectPath_Type);
 368     Py_INCREF(&DBusPyUTF8String_Type);
 369     Py_INCREF(&DBusPyString_Type);
 370     if (PyModule_AddObject(this_module, "ObjectPath",
 371                            (PyObject *)&DBusPyObjectPath_Type) < 0) return 0;
 372     if (PyModule_AddObject(this_module, "UTF8String",
 373                            (PyObject *)&DBusPyUTF8String_Type) < 0) return 0;
 374     if (PyModule_AddObject(this_module, "String",
 375                            (PyObject *)&DBusPyString_Type) < 0) return 0;
 376
 377     return 1;
 378 }
 379
 380 /* vim:set ft=c cino< sw=4 sts=4 et: */