RetsSession Class Reference

#include <librets/RetsSession.h>

List of all members.

---

Detailed Description

RetsSession contains the API that is the main controlling interface to the RETS server.

Public Member Functions
	RetsSession (std::string loginUrl)
	Create a new RETS session with a login URL.
	~RetsSession ()
std::string	GetLoginUrl () const
	Returns the LoginUrl that was used when this session was constructed.
bool	Login (std::string userName, std::string password)
	Logs into the RETS server.
bool	Login (std::string userName, std::string password, std::string brokerCode, std::string savedMetadataTimestamp)
	Logs into the RETS server with optional brokercode and saved metadata timestamp.
LoginResponse *	GetLoginResponse () const
	Returns the login response from the last successful login transaction.
CapabilityUrls *	GetCapabilityUrls () const
	Returns the capability URLs from the last successful login transaction.
std::string	GetAction ()
	Returns the contents of the action URL from the last successful login.
SearchRequestAPtr	CreateSearchRequest (std::string searchType, std::string searchClass, std::string query)
	Create a new search request with correct query type based on the detected version.
SearchResultSetAPtr	Search (SearchRequest *request)
	Performs a search on the server.
ServerInformationResponseAPtr	GetServerInformation (std::string resourceName="", std::string className="", bool standardNames=false)
	Create a new server information request (RETS 1.7).
RetsMetadata *	GetMetadata ()
	Returns the metadata for this server.
bool	IsIncrementalMetadata () const
	Returns true if metadata is retrieved incrementally.
void	SetIncrementalMetadata (bool incrementalMetadata)
	Changes how metadata is fetched.
GetObjectResponseAPtr	GetObject (GetObjectRequest *request)
	Fetches media from the server.
LogoutResponseAPtr	Logout ()
	Logs out of the server.
void	SetUserAgent (std::string userAgent)
	Sets the HTTP user agent.
void	UseHttpGet (bool useHttpGet)
	Use the HTTP GET method for GetMetadata, Seach, and GetObject requests.
void	SetHttpLogger (RetsHttpLogger *logger)
	Accepts a pointer to an instance of RetsHttpLogger to be used for logging.
void	SetHttpLogName (std::string logfile)
	Accepts a string that contains the name of a logfile.
RetsHttpLogger *	GetHttpLogger () const
	Returns a pointer to the instances of the RetsHttpLogger that will be/is being used.
RetsVersion	GetRetsVersion () const
	Return the RETS version to use when first logging in.
void	SetRetsVersion (RetsVersion retsVersion)
	Sets the RETS version to use when first logging in.
RetsVersion	GetDetectedRetsVersion () const
	Returns the RETS version detected by the login transaction and used by all subsequent transactions.
std::string	RetsVersionToString (RetsVersion retsVersion)
	Returns the RETS version as a printable string.
void	SetErrorHandler (RetsErrorHandler *errorHandler)
	Changes the error handler.
void	SetUserAgentAuthType (UserAgentAuthType type)
	Sets the User-Agent authorzation type.
UserAgentAuthType	GetUserAgentAuthType () const
	Returns the current User-Agent authorization type.
void	SetUserAgentPassword (std::string userAgentPassword)
	Sets the User-Agent password.
void	SetDefaultEncoding (EncodingType encoding)
	Sets the data encoding for the data to be returned by a Search.
void	SetLogEverything (bool logging)
	Sets the value of the flag that indicates everything should be logged, including everything from GetObject().
void	SetProxy (std::string url, std::string password)
	Set the html proxy information.
Static Public Member Functions
static std::string	GetLibraryVersion ()
	Return the version of libRETS.
Static Public Attributes
static const char *	DEFAULT_USER_AGENT
	Default user agent, for librets.
static const RetsVersion	DEFAULT_RETS_VERSION
	The default RETS version when logging in, 1.5.

---

Constructor & Destructor Documentation

RetsSession

(

std::string

loginUrl

)

Create a new RETS session with a login URL.

Parameters:

loginUrl

The login URL to a RETS server

Exceptions:

RetsException

if an error occurs.

~RetsSession

(

)

---

Member Function Documentation

std::string GetLoginUrl

(

)

const

Returns the LoginUrl that was used when this session was constructed.

Returns:

the login url

bool Login	(	std::string	userName,
		std::string	password
	)

Logs into the RETS server.

Parameters:

	userName	user name
	password	password

Returns:

True, if login is successful.

Exceptions:

RetsException

if an error occurs.

bool Login	(	std::string	userName,
		std::string	password,
		std::string	brokerCode,
		std::string	savedMetadataTimestamp
	)

Logs into the RETS server with optional brokercode and saved metadata timestamp.

Parameters:

	userName	user name
	password	password
	brokerCode	Broker Code
	savedMetadataTimestamp	The saved metadata timestamp (RETS 1.7+)

Returns:

True, if login is successful.

Exceptions:

RetsException

if an error occurs.

LoginResponse* GetLoginResponse

(

)

const

Returns the login response from the last successful login transaction.

If the last login trasaction was not successful, NULL is returned.

Returns:

Login response

Exceptions:

RetsEXception

if an error occurs.

CapabilityUrls* GetCapabilityUrls

(

)

const

Returns the capability URLs from the last successful login transaction.

If the last login transaction was not successful, NULL is returned.

Returns:

Capability URLs

Exceptions:

RetsException

if an error occurs.

std::string GetAction

(

)

Returns the contents of the action URL from the last successful login.

Returns:

the contents of the action URL

Exceptions:

RetsException

if an error occurs.

SearchRequestAPtr CreateSearchRequest	(	std::string	searchType,
		std::string	searchClass,
		std::string	query
	)

Create a new search request with correct query type based on the detected version.

Parameters:

	searchType	RETS resource name
	searchClass	RETS class name
	query	DMQL(2) query

SearchResultSetAPtr Search

(

SearchRequest *

request

)

Performs a search on the server.

Parameters:

request

search request parameters

Returns:

Search result set

Exceptions:

RetsException

if an error occurs.

ServerInformationResponseAPtr GetServerInformation	(	std::string	resourceName = "",
		std::string	className = "",
		bool	standardNames = false
	)

Create a new server information request (RETS 1.7).

Parameters:

	resourceName	RETS resource name
	className	RETS class name
	standardNames	true indicates Standard Names, false indicates System Names (default).

Returns:

Server Information Response.

RetsMetadata* GetMetadata

(

)

Returns the metadata for this server.

Only valid after logging in. This object is owned by the RetsSession and should not need to be deleted by the user.

Returns:

The metadata for this server

Exceptions:

RetsException

if an error occurs.

bool IsIncrementalMetadata

(

)

const

Returns true if metadata is retrieved incrementally.

Returns:

true if metadata is retreived incrementally.

void SetIncrementalMetadata

(

bool

incrementalMetadata

)

Changes how metadata is fetched.

If true, metadata is retrieved incrementally, as needed. If false, metadata is retreived all at once right after logging in. The default is true (incremental).

GetObjectResponseAPtr GetObject

(

GetObjectRequest *

request

)

Fetches media from the server.

Parameters:

request

A pointer to the GetObjectRequest containing the objects to fetch with this request.

LogoutResponseAPtr Logout

(

)

Logs out of the server.

Returns:

Logout information

Exceptions:

RetsException

if an error occurs.

void SetUserAgent

(

std::string

userAgent

)

Sets the HTTP user agent.

Parameters:

userAgent

HTTP user agent string.

void UseHttpGet

(

bool

useHttpGet

)

Use the HTTP GET method for GetMetadata, Seach, and GetObject requests.

The default is to use POST.

Parameters:

useHttpGet

true for HTTP GET instead of POST

void SetHttpLogger

(

RetsHttpLogger *

logger

)

Accepts a pointer to an instance of RetsHttpLogger to be used for logging.

Parameters:

logger

A pointer to the RetsHttpLogger to use.

void SetHttpLogName

(

std::string

logfile

)

Accepts a string that contains the name of a logfile.

Http logging will be enabled and the output will go to the named file.

Parameters:

logfile

A string containing the name of the log file.

RetsHttpLogger* GetHttpLogger

(

)

const

Returns a pointer to the instances of the RetsHttpLogger that will be/is being used.

RetsVersion GetRetsVersion

(

)

const

Return the RETS version to use when first logging in.

Returns:

RETS version to use when first logging in

void SetRetsVersion

(

RetsVersion

retsVersion

)

Sets the RETS version to use when first logging in.

Parameters:

retsVersion

RETS version to use when first logging in.

RetsVersion GetDetectedRetsVersion

(

)

const

Returns the RETS version detected by the login transaction and used by all subsequent transactions.

Returns:

the detected RETS version

std::string RetsVersionToString

(

RetsVersion

retsVersion

)

Returns the RETS version as a printable string.

Parameters:

retsVersion

RETS version to convert to a string.

Returns:

String representation of RETS version.

void SetErrorHandler

(

RetsErrorHandler *

errorHandler

)

Changes the error handler.

The default error handler throws exceptions in error conditions, which may not be desireable for some clients.

Parameters:

errorHandler

the new error handler.

void SetUserAgentAuthType

(

UserAgentAuthType

type

)

Sets the User-Agent authorzation type.

Currently, only Interealty is supported. Setting to any other value will raise an exception.

UserAgentAuthType GetUserAgentAuthType

(

)

const

Returns the current User-Agent authorization type.

void SetUserAgentPassword

(

std::string

userAgentPassword

)

Sets the User-Agent password.

void SetDefaultEncoding

(

EncodingType

encoding

)

Sets the data encoding for the data to be returned by a Search.

Thiss is session wide,

Parameters:

encoding

Either RETS_XML_DEFAULT_ENCODING or RETS_XML_ISO_ENCODING.

void SetLogEverything

(

bool

logging

)

Sets the value of the flag that indicates everything should be logged, including everything from GetObject().

Parameters:

logging

TRUE indicates to log everything, FALSE indicates to not log GetObject() requests.

void SetProxy	(	std::string	url,
		std::string	password
	)

Set the html proxy information.

Parameters:

	url	A string containing the url of the proxy server. If non-standard ports are used, it should be part of the url as in: http://demo.crt.realtors.org:6103.
	password	A string containing the proxy password if one is needed. This can be of the form "userid:password".

static std::string GetLibraryVersion

(

)

[static]

Return the version of libRETS.

Returns:

A string representing the libRETS version information.

---

Member Data Documentation

const char* DEFAULT_USER_AGENT [static]

Default user agent, for librets.

const RetsVersion DEFAULT_RETS_VERSION [static]

The default RETS version when logging in, 1.5.