SSML

Summary

SSML is a simple XML-like format describing structured data. It is presently used to transmit data from a Sayanara server on an EPOC device to a Linux client. If the full development path is realised it will be used to transfer information in the other direction.

The client applications have an SSML parser which understands SSML, parsers it and produces structures. Other C++ classes provide converters which take the SSML and output it as GNOME documents. Other converters could be provided.

Whitespace before and after tags means nothing. Presently the servers return neatly formatted, indented SSML - that'll likely change in the future to slightly improve transfer speed.

This document describes SSML in SAYANARA 1.0.1

SSML

SSML stands for something - I can't remember what now.

SSML contains text in a structure of tags. Each tag is a word in angle brackets e.g. <TAG>. Tags enclose data, so each opening tag must have a closing tag.

There are a few escape sequences:

sayancnt

The sayancnt server is accessed by opening a connection to the SYS$SAYANCNT server over the PLP link. It is a custom server according to the documentation.

The server present accepts two requests.

The request with opcode 2 is a request to open a contact database for reading. The content of the packet is the filename of the contact database on the EPOC device, which should be C:\SYSTEM\DATA\CONTACTS.CDB since this is the only contacts file the EPOC applications currently know about.

The request with opcode 1 is a request to fetch more data from an open contact database. The maximum amount of data which can be transferred in response is limited, so you'll have to make this call several times to get the data. When the data transfer is complete, this request will return of length zero. A pre-requisite to this call working is that the server has an open contact databased opened with an opcode 1 call.

There is no call to close the contact database. Closing the connection to the server does that.

The contacts datastream begins with an <contacts> tag and ends with an </contacts> tag. Inside these tags are a number of concatenated objects which start and end with a <contact> and </contact> tag.

Inside each contact object are a number of fields which begin and end with a <field> and </field> tag. Each field has a label, a type and a value part. The label, bounded by a LABEL tag is the label which appears in your contact application. It is locale-specific, so for label selection, use the type. The type is bounded by TYPE tags, and is a text string derived from the UIDs associated with the label. It is one of the following values:

        AdditionalName
        Birthday
        CompanyName
        FamilyName
        GivenName
        HomeAddress
        HomeCellPhoneNumber
        HomeCountry
        HomeEMail
        HomeExtendedAddress
        HomeFaxFax
        HomeLocality
        HomePagerPhoneNumber
        HomePhoneNumber
        HomePostCode
        HomePostOffice
        HomeRegion
        Note
        PrefixName
        SuffixName
        Url
        WorkAddress
        WorkEMail
        WorkFaxFax
        WorkLocality
        WorkPagerPhoneNumber
        WorkPhoneNumber
        WorkPostCode

The value part is in theory one of four types, and in practice one of two. It is usually a text value surrounded by TEXTVALUE tags except when it is the Birthday field in the contact entry, when it is surrounded by DATEVALUE tags.

  <contact>
    <field>
      <label>
        Company
      </label>
      <type>
        CompanyName
      </type>
      <textvalue>
        Fairtrade
      </textvalue>
    </field>
    <field>
      <label>
        Web page
      </label>
      <type>
        Url
      </type>
      <textvalue>
        www.fairtrade.org.uk
      </textvalue>
    </field>
    <field>
      <label>
        Notes
      </label>
      <type>
        Note
      </type>
      <textvalue>
        Fair trading with third world countries
      </textvalue>
    </field>
  </contact>

sayanagn

The sayanagn server is accessed by opening a connection to the SYS$SAYANAGN server over the PLP link. It is a custom server according to the documentation.

The server present accepts two requests.

The request with opcode 2 is a request to open an agenda database for reading. The content of the packet is the filename of the contact database on the EPOC device, probably C:\DOCUMENTS\AGENDA.

The request with opcode 1 is a request to fetch more data from an open agenda database. The maximum amount of data which can be transferred in response is limited, so you'll have to make this call several times to get the data. When the data transfer is complete, this request will return of length zero. A pre-requisite to this call working is that the server has an open contact databased opened with an opcode 1 call.

There is no call to close the agenda database. Closing the connection to the server does that.

The agenda datastream begins with an <agenda> tag and ends with an </agenda> tag. Inside these tags are objects of the following type: appt, daynote, event, todo, anniversary. Some examples. An appointment object for a standard Agenda appointment:

  <appt>
    <text>
      At the opera
    </text>
    <start>
      10/11/1999 19:30:00
    </start>
    <end>
      10/11/1999 21:30:00
    </end>
  </appt>

An anniversary:

  <anniversary>
    <text>
      Wedding anniversary
    </text>
    <start>
      14/09/1999
    </start>
  </anniversary>

A todo item:

  <todo>
    <crossedout>
      no
    </crossedout>
    <text>
      Buy train tickets
    </text>
    <priority>
      1
    </priority>
  </todo>

An event:

  <event>
    <text>
      In Tokyo
    </text>
    <start>
      15/02/2001
    </start>
    <end>
      19/02/2001
    </end>
  </event>

A daynote. This is entered as an appointment entry without a time in the Agenda application.

  <daynote>
    <text>
      Plumber coming 'round
    </text>
    <display>
      10/12/1999 06:00:00
    </display>
  </daynote>

(c) MA 2001.