RetsSession Class Reference

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

#include <librets/RetsSession.h>

Inheritance diagram for RetsSession:

MetadataLoader

List of all members.

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.
LoginResponseGetLoginResponse () const
 Returns the login response from the last successful login transaction.
CapabilityUrlsGetCapabilityUrls () 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.
void Search (SearchRequest *request, std::ostream &outputStream)
 Performs a search on the server, content is copied to output stream as the raw unparsed RETS data.
BinaryDataAPtr Search_ (SearchRequest *request)
 Performs a search on the server and return the data as BinaryDataPtr.
istreamPtr SearchStream (SearchRequest *request)
 Performs a search on the server and return the data as a stream.
public byte[] SearchAsArray (SearchRequest request)
 Performs a search on the server and returns the raw RETS data into a java byte array.
ServerInformationResponseAPtr GetServerInformation (std::string resourceName="", std::string className="", bool standardNames=false)
 Create a new server information request (RETS 1.7).
RetsMetadataGetMetadata ()
 Returns the metadata for this server.
void GetMetadata (std::ostream &outputStream)
 Copies the metadata for this server to the output stream as raw unparsed RETS data.
BinaryDataAPtr GetMetadata_ ()
 Copies the metadata on the server and returns the data as BinaryDataPtr.
public byte[] GetMetadataAsArray ()
 Gets the metadata on the server and returns the raw RETS data into a java byte array.
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.
RetsHttpLoggerGetHttpLogger () 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.
virtual void SetCollector (MetadataElementCollectorPtr collector)
 Sets the method that will be used to collect the metadata.
virtual void LoadMetadata (MetadataElement::Type type, std::string level)
 Fetch the specified metadata.
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 SetModeFlags (unsigned int flags)
 Set the mode flags for the current session.
void SetProxy (std::string url, std::string password)
 Set the html proxy information.
void SetTimeout (int seconds)
 Set a timeout value for the http transaction.
void Cleanup ()
 Cleans up/frees some underlying resources including the HTTP interface.
UpdateRequestAPtr CreateUpdateRequest (std::string resourceName, std::string className)
 Create a new update equest.
UpdateResponseAPtr Update (UpdateRequest *request)
 Performs an update on the server.

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.
static const int MODE_CACHE
 Mode flags for the current session.
static const int MODE_NO_STREAM
static const int MODE_NO_EXPECT
static const int MODE_NO_SSL_VERIFY


Detailed Description

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

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

void Cleanup (  ) 

Cleans up/frees some underlying resources including the HTTP interface.

This method is only really intended to be called by languages that have swig bindings so their final garbage collections work properly. C++ users should not need this method.

The RetsSession object should be considered unusuable after this call.

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

UpdateRequestAPtr CreateUpdateRequest ( std::string  resourceName,
std::string  className 
)

Create a new update equest.

Parameters:
resourceName RETS resource name
className RETS class name

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.

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.

RetsVersion GetDetectedRetsVersion (  )  const

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

Returns:
the detected RETS version

RetsHttpLogger* GetHttpLogger (  )  const

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

static std::string GetLibraryVersion (  )  [static]

Return the version of libRETS.

Returns:
A string representing the libRETS version information.

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.

std::string GetLoginUrl (  )  const

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

Returns:
the login url

void GetMetadata ( std::ostream &  outputStream  ) 

Copies the metadata for this server to the output stream as raw unparsed RETS data.

Only valid after logging in.

Parameters:
outputStream the destination stream
Returns:
nothing
Exceptions:
RetsException if an error occurs.

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.

BinaryDataAPtr GetMetadata_ (  ) 

Copies the metadata on the server and returns the data as BinaryDataPtr.

This API is primarily used by the SWIG bound languages.

Returns:
BinaryDataAPtr containing the metadata.
Exceptions:
RetsException if an error occurs.

public byte [] GetMetadataAsArray (  ) 

Gets the metadata on the server and returns the raw RETS data into a java byte array.

This API is for Java only.

Returns:
a Java byte array containing the search results as raw RETS data.

GetObjectResponseAPtr GetObject ( GetObjectRequest request  ) 

Fetches media from the server.

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

RetsVersion GetRetsVersion (  )  const

Return the RETS version to use when first logging in.

Returns:
RETS version to use when first logging in

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.

UserAgentAuthType GetUserAgentAuthType (  )  const

Returns the current User-Agent authorization type.

bool IsIncrementalMetadata (  )  const

Returns true if metadata is retrieved incrementally.

Returns:
true if metadata is retreived incrementally.

virtual void LoadMetadata ( MetadataElement::Type  type,
std::string  level 
) [virtual]

Fetch the specified metadata.

Parameters:
type The MetadataElement::Type for this request.
level A string containing the level for the current type.

Implements MetadataLoader.

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.

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.

LogoutResponseAPtr Logout (  ) 

Logs out of the server.

Returns:
Logout information
Exceptions:
RetsException if an error occurs.

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 Search ( SearchRequest request,
std::ostream &  outputStream 
)

Performs a search on the server, content is copied to output stream as the raw unparsed RETS data.

Parameters:
request search request parameters
outputStream the destination stream
Returns:
nothing
Exceptions:
RetsException if an error occurs.

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.

BinaryDataAPtr Search_ ( SearchRequest request  ) 

Performs a search on the server and return the data as BinaryDataPtr.

This API is primarily used by the SWIG bound languages.

Parameters:
request search request parameters
Returns:
BinaryDataAPtr containing the search results.
Exceptions:
RetsException if an error occurs.

public byte [] SearchAsArray ( SearchRequest  request  ) 

Performs a search on the server and returns the raw RETS data into a java byte array.

This API is for Java only.

Parameters:
request search request parameters
Returns:
a Java byte array containing the search results as raw RETS data.

istreamPtr SearchStream ( SearchRequest request  ) 

Performs a search on the server and return the data as a stream.

This API is primarily used by the SWIG bound languages.

Parameters:
request search request parameters
Returns:
BinaryDataAPtr containing the search results.
Exceptions:
RetsException if an error occurs.

virtual void SetCollector ( MetadataElementCollectorPtr  collector  )  [virtual]

Sets the method that will be used to collect the metadata.

Parameters:
collector A pointer to the MetadtaElementCollector.

Implements MetadataLoader.

void SetDefaultEncoding ( EncodingType  encoding  ) 

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

Thiss is session wide,

Parameters:
encoding RETS_XML_DEFAULT_ENCODING, RETS_XML_ISO_ENCODING or RETS_XML_UTF8_ENCODING.

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 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.

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).

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 SetModeFlags ( unsigned int  flags  ) 

Set the mode flags for the current session.

Parameters:
flags A logical OR of the flags to be set.

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".

void SetRetsVersion ( RetsVersion  retsVersion  ) 

Sets the RETS version to use when first logging in.

Parameters:
retsVersion RETS version to use when first logging in.

void SetTimeout ( int  seconds  ) 

Set a timeout value for the http transaction.

Parameters:
seconds An integer containing the number of seconds to set for the timeout. If zero, then no timeout is established and the default libCURL timeout will be in effect.

void SetUserAgent ( std::string  userAgent  ) 

Sets the HTTP user agent.

Parameters:
userAgent HTTP user agent string.

void SetUserAgentAuthType ( UserAgentAuthType  type  ) 

Sets the User-Agent authorzation type.

Parameters:
type Either USER_AGENT_AUTH_RETS_1_7 or USER_AGENT_AUTH_INTEREALTY

void SetUserAgentPassword ( std::string  userAgentPassword  ) 

Sets the User-Agent password.

UpdateResponseAPtr Update ( UpdateRequest request  ) 

Performs an update on the server.

Parameters:
request search request parameters
Returns:
Search result set
Exceptions:
RetsException if an error occurs.

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


Member Data Documentation

The default RETS version when logging in, 1.5.

const char* DEFAULT_USER_AGENT [static]

Default user agent, for librets.

const int MODE_CACHE [static]

Mode flags for the current session.

MODE_CACHE is used in streaming mode to enable the row cache. MODE_NO_STREAM will disable the streaming mode. MODE_NO_EXPECT will disable the Expect: 100-Continue http header. MODE_NO_SSL_VERIFY will disable verification of the certificate during SSL connections.

const int MODE_NO_EXPECT [static]

const int MODE_NO_SSL_VERIFY [static]

const int MODE_NO_STREAM [static]


Generated by  doxygen