> <?xml version="1.0"?> > <node name="/" > xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd";> <doc:doc> > <doc:summary>SyncEvolution D-Bus Interface</doc:summary> > </doc:doc> > <interface name="org.Moblin.SyncEvolution"> > > [should be renamed to org.syncevolution] > > <doc:doc> > <doc:para> > The SyncEvolution object can be used to get and set > configurations, to start synchronizations and to observe > synchronization progress. </doc:para> > </doc:doc> > > [...] > > <method name="Connect"> > <doc:doc> > <doc:summary> > Establishes a connection between SyncEvolution and a peer > (SyncML client or server). That peer might contact > SyncEvolution via D-Bus directly (local sync) or via a > SyncEvolution server stub that acts as gateway between a > peer that is connected to the stub via some other transport > mechanism (remote sync). For SyncEvolution this difference > is almost completely transparent. > > In contrast to connections established by SyncEvolution > itself, the peer has to send the first message and > SyncEvolution replies. If the first message is a normal > SyncML message, then SyncEvolution acts as SyncML server. > Alternatively, a Notification message can be sent to request > that SyncEvolution initiates a SyncML session as client. > > In the later case, SyncEvolution may or may not use the > connection established by Connect(), depending on the > content of that first message. > > The result of Connect() is an object that implements the > org.syncevolution.connection interface. It has to be used > for sending at least one message to start the sync. If > SyncEvolution needs to abort the connection, it will delete > that object. A peer needs to subscribe to the delete signal > to detect this situation. This also covers the situation > that SyncEvolution quits unexpectedly. > > SyncEvolution supports re-establishing a connection that was > interrupted. This only works when the peer is a SyncML > client, supports resending messages, and the non-D-Bus > message transport supports sending the session number as > part of the meta information. > </doc:summary> > </doc:doc> > <arg type="s" name="peer_description" direction="in"> > <doc:doc> > <doc:summary> > A description of the peer in a format and language that is > understood by the user. > </doc:summary> > </doc:doc> > </arg>
Take OBEX server/SyncML client binding for example, what name is appropriate for "peer_description"? > <arg type="s" name="peer_id" direction="in"> > <doc:doc> > <doc:summary> > A unique ID for this particular peer, in a format that is > specific to the transport. The ID only has to be unique > among peers using that transport at the current point in > time. > </doc:summary> > </doc:doc> > </arg> > <arg type="s" name="transport" direction="in"> > <doc:doc> > <doc:summary> > A string identifying the entity which talks directly > to SyncEvolution (peer or transport stub). If available, > this should be a D-Bus interface name. The main purpose > right now is for informing the user and debugging. > Later it might also be used to call methods in that > interface or for choosing a local configuration for > the peer based on its ID. > </doc:summary> > </doc:doc> > </arg> Is it appropriate to set "transport" to "OBEX" in obexd plugin? > <arg type="b" name="must_authenticate" direction="in"> > <doc:doc> > <doc:summary> > If false, then the peer is trusted and shall be given > access to SyncEvolution without further checks by > SyncEvolution itself. This is useful for peers which > already run as local user processes with same access > rights to the data as SyncEvolution or for transports that > authenticate and authorize access via their own > mechanisms. > > If true, then a SyncML client peer must provide valid > credentials as part of the SyncML session. For a server, > a valid configuration must exist. SyncEvolution searches > for such a configuration by matching the sync URL in > the Notification with sync URLs in the configurations. > </doc:summary> > </doc:doc> > </arg> How should obexd plugin know if the SyncML-level authentication is needed? > <arg type="u" name="session" direction="in"> > <doc:doc> > <doc:summary> > If this is a reconnect for an older session, > then pass the session number here. Otherwise > pass 0. New session numbers are created in > response to the initial message. > </doc:summary> > </doc:doc> > </arg> For OBEX session is always 0 since OBEX has no mechanism to support reconnection. > <arg type="o" name="connection" direction="out"> > <doc:doc> > <doc:summary> > The connection object created by SyncEvolution in response > to this connection request. Implements the > org.syncevolution.connection interface. > </doc:summary> > </doc:doc> > </arg> > </method> > </interface> > > <interface name="org.syncevolution.connection"> > <doc:doc> > <doc:para> > The SyncEvolution connection object can be used to exchange > messages. > </doc:para> > </doc:doc> > > <method name="Process"> > <doc:doc> > <doc:summary> > Pass data to SyncEvolution and get the response. > </doc:summary> > </doc:doc> > > <arg type="ay" name="message" direction="in"> > <doc:doc> > <doc:summary> > The data to be processed. Empty messages are invalid > and will trigger an error. > </doc:summary> > </doc:doc> > </arg> > If the message is too long, OBEX would split the message into muliple packets and send them seperately. It would be nice for SyncEvolution to provide a API to transmit multiple packets belonging to one message. > <arg type="s" name="message_type" direction="in"> > <doc:doc> > <doc:summary> > The MIME type of the > message. "application/vnd.syncml.ds.notification", > "application/vnd.syncml+xml" and > "application/vnd.syncml+wbxml" are currently supported. > </doc:summary> > </doc:doc> > </arg> > > <arg type="ay" name="reply" direction="out"> > <doc:doc> > <doc:summary> > The data to be returned to the peer. An empty reply is > possible as response to the last message; it must not be > delivered. Instead, final will be true and the connection > needs to be closed. > </doc:summary> > </doc:doc> > </arg> > I'm afraid this way of returning data does not work. Please read section 6.2 of http://www.openmobilealliance.org/Technical/release_program/docs/copyrightclick.aspx?pck=DS&file=V2_0-20090212-C/OMA-TS-SyncML_OBEXBinding-V1_2-20070221-A.pdf. OBEX client first send SyncML request to OBEX server by PUT command; then OBEX server can't return data to OBEX client actively. OBEX client has to send GET command to pull results. > <arg type="s" name="response_type" direction="out"> > <doc:doc> > <doc:summary> > The MIME type of the response. The same types as for the > message are supported. > </doc:summary> > </doc:doc> > </arg> > > <arg type="s" name="response_url" direction="out"> > <doc:doc> > <doc:summary> > The content of the string depends on the transport, which > must be recognized by SyncEvolution if special information > is required. By default and if applicable, the URL for an > HTTP POST is passed here. > </doc:summary> > </doc:doc> > </arg> > > <arg type="b" name="final" direction="out"> > <doc:doc> > <doc:summary> > True if this is the last reply. No further messages are > expected and the session should be closed once the reply > was delivered successfully. > </doc:summary> > </doc:doc> > </arg> > > <arg type="u" name="session" direction="out"> > <doc:doc> > <doc:summary> > The first message in a new connection triggers the > creation of a new, random session number which is returned > together with the response. The caller is responsible for > ensuring that only messages belonging to this session are > passed to future process() calls. > > In practice the session number does not change after the > first message, but this is not guaranteed and the caller > should always use the most recent value. > </doc:summary> > </doc:doc> > </arg> > </method> > > <method name="Close"> > <doc:doc> > <doc:summary> > Indicates that the connection object is no longer needed. > </doc:summary> > </doc:doc> > > <arg type="b" name="normal" direction="in"> > <doc:doc> > <doc:summary> > TRUE if the connection is being closed after successfully > delivering the final response. FALSE if an error is > encountered that cannot be handled by the peer or its > transport. SyncEvolution cannot rely on getting a > close(FALSE) call in all cases. If its caller disappears > from the bus it must assume that there was a fatal error > and close the connection. > </doc:summary> > </doc:doc> > </arg> > > <arg type="s" name="error" direction="in"> > <doc:doc> > <doc:summary> > A description which explains the error, may be empty. > Used for debugging. > </doc:summary> > </doc:doc> > </arg> > </method> > </interface> _______________________________________________ SyncEvolution mailing list [email protected] http://lists.syncevolution.org/listinfo/syncevolution
