О формате XML

[client]

"Немного" про XML, используемый клиентом при операциях импорта/экспорта.
 
В принципе, можно просто сделать экспорт нужного элемента и посмотреть на результат в Блокноте или IE, там все достаточно очевидно. Есть, впрочем, некоторые тонкости, ради которых я опишу подробнее про формат.
 
Вот так примерно выглядит XML-файл:
 
<?xml version="1.0" encoding="utf-8"?>
<diaryClient>
  <info>
    <generated>12.10.2007 05:05:20</generated>
    <software>@Diary.Client 0.4.7.1</software>
    <version>1</version>
  </info>
  <events>
    <item type="error" subtype="error" date="12.10.2007 04:36:13" read="true">
      <title><![CDATA[Смена пароля отложена]]></title>
      <source><![CDATA[Проверка избранного]]></source>
      <details><![CDATA[]]></details>
    </item>
    <item type="error" subtype="error" date="12.10.2007 04:36:13" read="true">
      <title><![CDATA[Смена пароля отложена]]></title>
      <source><![CDATA[Проверка избранных через Web]]></source>
      <details><![CDATA[]]></details>
    </item>
  </events>
</diaryClient>
 
Корневым элементом всегда является элемент diaryClient, внутри которого находится несколько независимых секций.
 
Секция info содержит информацию о файле. Единственное обязательное значение здесь - version, указывающее на версию формата. На данный момент существует только одна версия ("1"). Все остальные значения создаются для информации и не используются при импорте; Вы можете записать сюда все, что необходимо Вам для работы.
 
Все остальные секции содержат непосредственно данные, их содержание определяется названием. Кстати, в одном файле может быть несколько различных секций с данными (напр., события и посты), но двух секций с одним названием - нет.
 
Везде, кроме постов, значений для элемента не много, поэтому все перечисленные значения являются обязательными. У поста может быть много атрибутов, и, дабы не создавать путаницу, почти все сделаны опциональными - подробнее см. в описании соответствующей секции.
 
events:
События. К событиям у нас относится все, что отображается на вкладках "ПЧ и ИД" a.k.a. "События" и "Ошибки" - появление, исчезновение, переименование ПЧ, ИД, и логи ошибок. Каждая запись представлена элементом item.
Атрибуты:
– type - "error", "reader", "friend", "subscriber" или "community", в зависимости от типа записи (error - сообщения об ошибках, reader - сообщения, относящиеся к списку ПЧ, friend - к списку ИД, subscriber - к подпискам на e-mail, community - к событиям сообщества);
– subtype - для типов error, reader, friend, subscriber:
   "error", "new", "lost", "rename" в зависимости от конкретного события (значение, думаю, очевидно ^^);
для типа community список возможных значений: newmember (новый член сообщества), lostmember (уход члена сообщ-ва), renamemember (переименование члена сообщ-ва), newrequest (новый запрос на вступление), lostrequest (отмена запроса), renamerequest (переименование пользователя, подавшего запрос), requestrefused (во вступлении отказано), requestaccepted (запрос принят), requestautorefused (программа автоматически дала отказ на вступление);
– date - дата события. Это строка, и после импорта отображаться будет так, как написано в XML-файле. Экспорт производится в формате DD.MM.YYYY HH:NN:SS;
– read - "true" или "false", флаг прочтения сообщения (true - сообщение уже прочитано).
Элементы:
– title - заголовок или краткое описание (краткий текст ошибки или логин ПЧ/ИД);
– source - источник ошибки (для ПЧ и ИД не выводится);
– details - подробная информация.
 
<item type="error" subtype="error" date="12.10.2007 04:36:13" read="true">
  <title><![CDATA[Смена пароля отложена]]></title>
  <source><![CDATA[Проверка избранного]]></source>
  <details><![CDATA[]]></details>
</item>
 
images:
Изображения библиотеки изображений. (Эта секция будет поддерживаться только с версии 0.4.8). Каждое изображение представлено элементом item, содержащим следующие дочерние элементы:
– store - число, определяющее хранилище (0 - БИ, 1 - imageshack.us);
– id - идентификатор картинки в БИ @дневников. Это значение в настоящее время не используется, но в старых версиях оно использовалось для генерации URL картинки, поэтому оно сохранено из соображений совместимости;
– url - адрес картинки;
– preview - адрес превью;
– previewfile - имя локального файла-превью;
– file - имя файла локальной копии картинки;
– previewdata - этот элемент может отсутствовать; если он присутствует, то он должен содержать BASE64-закодированный файл превью;
– imagedata - аналогично для полноразмерного файла.
 
<item>
  <store>0</store>
  <id><![CDATA[]]></id>
  <url><![CDATA[static.diary.ru/userdir/3/6/2/9/362988/25233959...]]></url>
  <preview><![CDATA[static.diary.ru/userdir/3/6/2/9/362988/thumb/25...]]></preview>
  <file><![CDATA[fullsized-25233959.jpg]]></file>
  <previewfile><![CDATA[preview-25233959.jpg]]></previewfile>
  <previewdata><![CDATA[/9j/4AAQSkZJR...E+mqWrvP/9k=]]></previewdata>
  <imagedata><![CDATA[/9j/4AAQSkZJR...SUgf+W//2Q==]]></imagedata>
</item>
 
 
umail:
U-mail'ы. Внутри - отдельные письма, представленные элементами item.
Атрибуты:
– id - это ID сообщения на сервере. На данный момент ID используется исключительно для того, чтобы избежать появления дубликатов при импорте с сервера, и в базе клиента ID имеют только входящие письма. Если ID не известен, можно оставить атрибут пустым (или указать что-то абстрактное, имеющее другое значение, максимум 10 символов);
– read - "true" или "false", флаг прочтения сообщения (true - сообщение прочитано);
– folder - "inbox", "outbox", "sent" или "trash" - папка, содержащая сообщение;
– report - "true" или "false", указывает, будет ли или был ли запрошен отчет о доставке;
– compiled - "true" или "false". Этот флаг влияет на интерпретацию значения "content". Если compiled="false", то тело письма (content) должно представлять собой корректный с точки зрения сайта BBCode+HTML (т.е. содержать только то, что разрешено при отправке писем на сайте) и может содержать спецсимволы Юникода. Если compiled="true", то тело письма может содержать произвольный HTML и он будет корректно обработан при коммуникации с сервером, но тело письма должно содержать только символы одной кодировки (в частности - символы, имеющие аналоги в таблице windows-1251), спецсимволы нужно закодировать как HTML-коды. В общем случае, если вы готовите письма к отправке из клиента, ставьте compiled="false" и не заморачивайтесь *)
Элементы:
– time - дата/время письма. Так же как с событиями, это - строка; тут можно написать что угодно, и оно отобразится. Это поле используется для сортировки по дате, поэтому лучше соблюдать формат, принятый на сайте;
– username - имя пользователя (получателя или отправителя, в зависимости от папки);
– title - заголовок;
– content - тело письма;
– uploads - список приложенных файлов. Эта секция имеет одинаковый формат у писем и записей дневника и может иметь ссылки на секцию attachments, подробнее - см. в секции attachments.
 
<item id="12178080" compiled="true" read="true" folder="inbox" report="false">
  <time><![CDATA[10.11.2006 09:48]]></time>
  <username><![CDATA`Gonzales`]></username>
  <title><![CDATA[Уведомление: Re[5]: никнейм]]></title>
  <content><![CDATA[<div>Ваше сообщение было прочитано 2006.11.10 09:48</div>]]></content>
  <uploads></uploads>
</item>
 
 
posts:
Посты дневника. Каждый пост представлен отдельным элементом item.
 
Немного о методе хранения постов в программе. Каждому посту при сохранении присваивается некий уникальный идентификатор (число). В дальнейшем все ссылки на каждый пост делаются по этому идентификатору. Соответственно, режим импорта постов (т.е. будет ли элемент импортирован как новый пост или заменил ли элемент уже имеющуюся запись) зависит от указанного ID.
 
Атрибуты:
– id - идентификатор поста (число). Если указать ID и пост с этим ID будет найден в базе, то найденный пост будет заменен на пост из XML-файла. Если пост не найдется - будет создан новый с указанным ID. Если ID не указывать (либо это будет ноль или не число) - будет создан новый пост и новый ID ему будет присвоен автоматически.
– diary - ID дневника или сообщества, в который отправляется/отправлен пост. Чтобы определить пост в личный дневник, можно указать его ID или оставить пустым (либо не указывать вообще). Обратите внимание, что "пустым" - это именно "пустым", а не нулевым ("0"). Можно и просто пропустить этот атрибут (см. замечание про значения по умолчанию ниже);
– server - ID поста на сервере;
– unique - любая строка, содержащаяся в теле поста и уникально его иденифицирующая. Это значение используется только при определении ID поста. Обратите внимание, что при отправке неотправленных постов значение переназначается автоматически, так что обычно его можно не указывать. (Единственное применение этого значения - сообщить клиенту о наличии отправленно поста с известной датой и содержимым, но неизвестным ID.);
– state - "notsent", "sent" или "modified", в зависимости от статуса отправки поста;
– smileys - "true" или "false", флаг разрешения графических смайлов (если смайлы запрещены, то smileys="false"!);
– comments - аналогично для разрешения комментариев;
– signature - аналогично для подписи (signature="true" разрешает добавлять подпись, если она задана в настройках, signature="false" - не разрешает);
– email - аналогично для флага "Не рассылать на e-mail подписчикам" (email="true" - рассылать можно, email="false" - не рассылать);
– schedule - "true" или "false", разрешает или запрещает отправку или обновление поста автоматически (по расписанию);
– nosend - "true" или "false", флаг "Не отправлять" (nosend="true" - не отправлять, nosend="false" - можно отправлять);
– asnew - аналогично для флага "Считать новой" или "Вернуть на место" (для отправленных записей);
– asnewmode - метод изменения позиции записи: up - поднять запись, return - вернуть на место;
– backdated - аналогично asnew для флага отправки задним числом (backdated="true" - пытаться отправить задним числом, backdated="false" - отправлять текущим);
– date - дата и время поста в формате DD.MM.YYYY HH:NN:SS;
– creation_date - "базовые" дата и время поста в формате DD.MM.YYYY HH:NN:SS. Это поле должно быть заполнено, если запись когда-то была поднята с помощью опции "Считать новой", и содержать первоначальную дату отправки записи; в противном случае - атрибут отсутствует;
– saved - дата и время создания поста в формате DD.MM.YYYY HH:NN:SS. Это значение нигде не используется и присутствует в базе по историческим причинам, поэтому его можно свободно пропустить;
– avatar - ID аватара; ноль, если аватар не выбран.
Элементы:
– title - заголовок поста;
– content - текст поста;
– music - @музыка;
– mood - @настроение;
– access - установки доступа. Этот элемент содержит список доступа (или пуст, если список доступа пустой или не указан); атрибуты определяют режим доступа: enabled="true" - закрытая запись, enabled="false" - запись открыта; mode - опции доступа ("favorite" или "1" - открыта для избранных, "invisible" или "2" - закрыта для списка, "visible" или "3" - открыта для списка, "whitelist" или "4" - открыта для белого списка), adult - "true", если запись содержит материалы для взрослых, "false" в противном случае. Если атрибут mode не распознан, устанавливается режим "открыто для белого списка";
– alternate - альтернативный текс закрытой записи. Этот элемент содержит сам текст; его атрибут enabled определяет состояние соответствующего флажка: enabled="true" - альтернативный текст используется, enabled="false" - альтернативный текст не используется;
– tags: @темы. Содержит любое число элементов item, содержание которых - ID тем, установленых посту;
– poll: опрос. Атрибуты: multi - "true" или "false", определяет возможность выбора нескольких вариантов одновременно; close - "true" или "false" - флаг "Закрыть опрос" (для отправленных записей), delete - аналогично для флага "Удлалить опрос". Дочерние элементы: title - заголовок опроса, item - варианты ответов (до 10 шт.);
– uploads - список приложенных файлов. Эта секция имеет одинаковый формат у писем и записей дневника и может иметь ссылки на секцию attachments, подробнее - см. в секции attachments.
 
Все атрибуты и дочерние элементы для каждого поста являются необязательными; если атрибут или элемент пропущен, посту устанавливается значение по умолчанию. Для простоты, ниже приведен код для поста, в котором все атрибуты и элементы установлены в значения по умолчанию.
Обратите внимание, что вы можете пропустить элементы access, poll, tags, uploads целиком, но если вы их используйте, указывайте все значения! Например, нельзя пропустить значение access.mode или poll.title. Запись <tags /> или <uploads />, так же как и <tags></tags> или <uploads></uploads> является корректной и означает отсутствие соответствующих элементов; впрочем, в этом случае указанные элементы вообще можно пропустить.
 
Итак, значения по умолчанию. Обратите внимание на backdated="false"!
<item id="0" diary="" server="" unique="" state="notsent" smileys="true" comments="true" saved="{дата и время на компьютере в момент импорта}" date="{дата и время на компьютере в момент импорта}" backdated="false" nosend="false" signature="true" asnew="false" email="true" schedule="true" avatar="0">
  <title />
  <content />
  <music />
  <mood />
  <access enabled="false" mode="whitelist" adult="false" />
  <alternate enabled="false" />
  <poll close="false" delete="false" multi="false">
    <title />
  </poll>
  <uploads />
  <tags />
</item>
 
attachments:
В этой секции хранятся файлы, приложенные к постам и письмам, если они не были сохранены как отдельные файлы (т.е. отдельно от XML-файла). Каждый файл представлен элементом item, имеющим обязательный атрибут id - идентификатор файла. Идентификатор - произвольная строка, которая должна быть уникальной в пределах XML-файла. Содержание элемента item - закодированное в BASE64 содержимое приложенного файла.
 
Хранение приложенных файлов в постах и письмах реализуется с помощью вложенного элемента uploads (см. секции posts, umails). Содержимое раздела uploads - произвольное число элементов file, имеющих один обязательный атрибут - id (индекс приложенного файла); содержание этого элемента определяется наличием атрибута refid:
– если refid не установлен, то эта запись представляет собой ссылку на произвольный файл на диске, путь к которому сохраняется в качестве содержимого элемента file:
<file id="1"><![CDATA[D:\My Pictures\Photo.jpg]]></file>
– если refid установлен, то этот элемент является ссылкой на файл, сохраненный в секции attachments и имеющий ID, определенный значением атрибута refid. Содержанием элемента file в данном случае является только имя файла:
<file id="2" refid="1"><![CDATA[Photo.jpg]]></file>