2009-02-15 15:22:07 +01:00
|
|
|
/*
|
2009-03-25 15:21:04 +01:00
|
|
|
* Copyright (C) 2009 Intel Corporation
|
2009-02-15 15:22:07 +01:00
|
|
|
*
|
2009-04-30 18:35:56 +02:00
|
|
|
* This library is free software; you can redistribute it and/or
|
|
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
|
|
* License as published by the Free Software Foundation; either
|
|
|
|
* version 2.1 of the License, or (at your option) version 3.
|
2009-02-15 15:22:07 +01:00
|
|
|
*
|
2009-04-30 18:35:56 +02:00
|
|
|
* This library is distributed in the hope that it will be useful,
|
2009-02-15 15:22:07 +01:00
|
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
2009-04-30 18:35:56 +02:00
|
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
|
|
* Lesser General Public License for more details.
|
2009-02-15 15:22:07 +01:00
|
|
|
*
|
2009-04-30 18:35:56 +02:00
|
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
|
|
* License along with this library; if not, write to the Free Software
|
|
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
|
|
* 02110-1301 USA
|
2009-02-15 15:22:07 +01:00
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef INCL_TRANSPORTAGENT
|
|
|
|
#define INCL_TRANSPORTAGENT
|
|
|
|
|
|
|
|
#include <string>
|
2009-10-05 14:49:32 +02:00
|
|
|
#include <syncevo/util.h>
|
2009-02-15 15:22:07 +01:00
|
|
|
|
2009-10-05 14:49:32 +02:00
|
|
|
#include <syncevo/declarations.h>
|
2009-10-02 17:23:53 +02:00
|
|
|
SE_BEGIN_CXX
|
|
|
|
|
2009-10-07 17:57:38 +02:00
|
|
|
class SyncConfig;
|
2009-02-15 15:22:07 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Abstract API for a message send/receive agent.
|
|
|
|
*
|
|
|
|
* The calling sequence is as follows:
|
|
|
|
* - set parameters for next message
|
|
|
|
* - start message send
|
|
|
|
* - optional: cancel transmission
|
2009-10-07 17:57:38 +02:00
|
|
|
* - wait for completion and the optional reply
|
|
|
|
* - close
|
|
|
|
* - wait for completion of the shutdown
|
2009-02-15 15:22:07 +01:00
|
|
|
*
|
|
|
|
* Data to be sent is owned by caller. Data received as reply is
|
2009-02-20 19:20:08 +01:00
|
|
|
* allocated and owned by agent. Errors are reported via
|
|
|
|
* TransportAgentException.
|
2009-02-15 15:22:07 +01:00
|
|
|
*/
|
|
|
|
class TransportAgent
|
|
|
|
{
|
|
|
|
public:
|
2009-10-07 17:57:38 +02:00
|
|
|
typedef bool (*TransportCallback) (void *udata);
|
|
|
|
|
2009-02-15 15:22:07 +01:00
|
|
|
/**
|
|
|
|
* set transport specific URL of next message
|
|
|
|
*/
|
|
|
|
virtual void setURL(const std::string &url) = 0;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* define content type for post, see content type constants
|
|
|
|
*/
|
|
|
|
virtual void setContentType(const std::string &type) = 0;
|
|
|
|
|
2009-02-24 12:21:48 +01:00
|
|
|
/**
|
2009-10-07 17:57:38 +02:00
|
|
|
* Requests an normal shutdown of the transport. This can take a
|
|
|
|
* while, for example if communication is still pending.
|
|
|
|
* Therefore wait() has to be called to ensure that the
|
|
|
|
* shutdown is complete and that no error occurred.
|
|
|
|
*
|
|
|
|
* Simply deleting the transport is an *unnormal* shutdown that
|
|
|
|
* does not communicate with the peer.
|
2009-02-24 12:21:48 +01:00
|
|
|
*/
|
2009-10-07 17:57:38 +02:00
|
|
|
virtual void shutdown() = 0;
|
2009-02-24 12:21:48 +01:00
|
|
|
|
2009-02-15 15:22:07 +01:00
|
|
|
/**
|
|
|
|
* start sending message
|
|
|
|
*
|
|
|
|
* Memory must remain valid until reply is received or
|
|
|
|
* message transmission is canceled.
|
|
|
|
*
|
|
|
|
* @param data start address of data to send
|
|
|
|
* @param len number of bytes
|
|
|
|
*/
|
|
|
|
virtual void send(const char *data, size_t len) = 0;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* cancel an active message transmission
|
|
|
|
*
|
|
|
|
* Blocks until send buffer is no longer in use.
|
|
|
|
* Returns immediately if nothing pending.
|
|
|
|
*/
|
|
|
|
virtual void cancel() = 0;
|
|
|
|
|
|
|
|
enum Status {
|
|
|
|
/**
|
2009-10-07 17:57:38 +02:00
|
|
|
* operation is on-going, check again with wait()
|
2009-02-15 15:22:07 +01:00
|
|
|
*/
|
|
|
|
ACTIVE,
|
|
|
|
/**
|
|
|
|
* received and buffered complete reply,
|
2009-10-07 17:57:38 +02:00
|
|
|
* get access to it with getReponse()
|
2009-02-15 15:22:07 +01:00
|
|
|
*/
|
|
|
|
GOT_REPLY,
|
|
|
|
/**
|
|
|
|
* message wasn't sent, try again with send()
|
|
|
|
*/
|
|
|
|
CANCELED,
|
|
|
|
/**
|
2009-07-28 07:21:27 +02:00
|
|
|
* sending message has failed, transport should not throw an exception
|
|
|
|
* if the error is recoverable (such as a temporary network error)
|
2009-02-15 15:22:07 +01:00
|
|
|
*/
|
|
|
|
FAILED,
|
2009-10-07 17:57:38 +02:00
|
|
|
/**
|
|
|
|
* transport was closed normally without error
|
|
|
|
*/
|
|
|
|
CLOSED,
|
2009-07-22 10:44:06 +02:00
|
|
|
/**
|
|
|
|
* transport timeout
|
|
|
|
*/
|
|
|
|
TIME_OUT,
|
2009-02-15 15:22:07 +01:00
|
|
|
/**
|
|
|
|
* unused transport, configure and use send()
|
|
|
|
*/
|
|
|
|
INACTIVE
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
2009-10-07 17:57:38 +02:00
|
|
|
* Wait for completion of an operation initiated earlier.
|
|
|
|
* The operation can be a send with optional reply or
|
|
|
|
* a close request.
|
2009-02-15 15:22:07 +01:00
|
|
|
*
|
2009-10-07 17:57:38 +02:00
|
|
|
* Returns immediately if no operations is pending.
|
|
|
|
*
|
|
|
|
* @param noReply true if no reply is required for a running send;
|
|
|
|
* only relevant for transports used by a SyncML server
|
2009-02-15 15:22:07 +01:00
|
|
|
*/
|
2009-10-07 17:57:38 +02:00
|
|
|
virtual Status wait(bool noReply = false) = 0;
|
2009-02-15 15:22:07 +01:00
|
|
|
|
2009-07-22 10:44:06 +02:00
|
|
|
/**
|
2010-01-14 11:59:05 +01:00
|
|
|
* The callback is called at most once while a transmission is
|
|
|
|
* pending, "interval" seconds after calling send(), with udata as
|
|
|
|
* the last parameter. When the callback returns true, the
|
|
|
|
* transport will stop waiting for a reply to the message and flag
|
|
|
|
* a timeout. When the callback returns false, the transport will
|
|
|
|
* cancel the transmission.
|
2009-07-22 10:44:06 +02:00
|
|
|
*/
|
|
|
|
virtual void setCallback (TransportCallback cb, void * udata, int interval) = 0;
|
|
|
|
|
2009-02-15 15:22:07 +01:00
|
|
|
/**
|
|
|
|
* provides access to reply data
|
|
|
|
*
|
|
|
|
* Memory pointer remains valid as long as
|
|
|
|
* transport agent is not deleted and no other
|
|
|
|
* message is sent.
|
|
|
|
*/
|
2009-03-31 15:25:47 +02:00
|
|
|
virtual void getReply(const char *&data, size_t &len, std::string &contentType) = 0;
|
2009-02-15 15:22:07 +01:00
|
|
|
|
|
|
|
/** SyncML in XML format */
|
|
|
|
static const char * const m_contentTypeSyncML;
|
|
|
|
|
|
|
|
/** SyncML in WBXML format */
|
|
|
|
static const char * const m_contentTypeSyncWBXML;
|
|
|
|
|
|
|
|
/** normal HTTP URL encoded */
|
|
|
|
static const char * const m_contentTypeURLEncoded;
|
2009-09-21 15:25:14 +02:00
|
|
|
|
|
|
|
/** binary Server Alerted Notification (SAN) for data sync */
|
|
|
|
static const char * const m_contentTypeServerAlertedNotificationDS;
|
2009-10-07 17:57:38 +02:00
|
|
|
};
|
2009-07-22 10:44:06 +02:00
|
|
|
|
2009-10-07 17:57:38 +02:00
|
|
|
class HTTPTransportAgent : public TransportAgent
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
* set proxy for transport, in protocol://[user@]host[:port] format
|
|
|
|
*/
|
|
|
|
virtual void setProxy(const std::string &proxy) = 0;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* set proxy user name (if not specified in proxy string)
|
|
|
|
* and password
|
|
|
|
*/
|
|
|
|
virtual void setProxyAuth(const std::string &user,
|
|
|
|
const std::string &password) = 0;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* control how SSL certificates are checked
|
|
|
|
*
|
|
|
|
* @param cacerts path to a single CA certificate file
|
|
|
|
* @param verifyServer enable server verification (should always be on)
|
|
|
|
* @param verifyHost do strict hostname checking in the certificate
|
|
|
|
*/
|
|
|
|
virtual void setSSL(const std::string &cacerts,
|
|
|
|
bool verifyServer,
|
|
|
|
bool verifyHost) = 0;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* override default user agent string
|
|
|
|
*/
|
|
|
|
virtual void setUserAgent(const std::string &agent) = 0;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* convenience method which copies the HTTP settings from
|
|
|
|
* SyncConfig
|
|
|
|
*/
|
|
|
|
void setConfig(SyncConfig &config);
|
2009-02-15 15:22:07 +01:00
|
|
|
};
|
|
|
|
|
2009-10-07 17:57:38 +02:00
|
|
|
|
2009-10-06 17:22:47 +02:00
|
|
|
class TransportException : public Exception
|
2009-02-20 19:20:08 +01:00
|
|
|
{
|
|
|
|
public:
|
|
|
|
TransportException(const std::string &file,
|
|
|
|
int line,
|
|
|
|
const std::string &what) :
|
2009-10-06 17:22:47 +02:00
|
|
|
Exception(file, line, what) {}
|
2009-02-20 19:20:08 +01:00
|
|
|
~TransportException() throw() {}
|
|
|
|
};
|
|
|
|
|
2009-02-15 15:22:07 +01:00
|
|
|
|
2009-10-02 17:23:53 +02:00
|
|
|
SE_END_CXX
|
2009-02-15 15:22:07 +01:00
|
|
|
#endif // INCL_TRANSPORTAGENT
|