|
As defined in xcapi.h
| xerr xcCreateSession( | XC_OBJECT_TYPE session_type, |
| xhandle *session, | |
| xcObjectCallback callback, | |
| xuint64 turnkey, | |
| const char *server_list, | |
| const char *username, | |
| const char *password); |
Description:
Initiates a session with an Exegy appliance by establishing a connection, authenticating and authorizing the user, and creating a session object. The session object is then available to the client application for creating any number of container objects.
Note that if the session, userid or password parameter values are supplied as NULL, no object is created, no event notification occurs, and the function returns a status of XINVAL.
The function is synchronous, and will not return until a connection with an Exegy appliance is either successfully established or XCAPI determines that no connection can be established. The latter determination is made only if XCAPI has cycled through each appliance specified in the server_list parameter, and a connection attempt to each has failed. (In addition, no previous connection for the Session instance can have been successful; if there was previously a successful connection, then XCAPI's disconnect logic is invoked, whereby XCAPI continues to cycle through the list of servers and does not terminate or return.) If no initial connection with an appliance can be established, the session object is automatically destroyed before xcCreateSession() returns. Note that the callback (if one was specified) may return before or after xcCreateSession() returns.
While multiple session objects may be created on the client, the number of session instances cannot exceed the maximum number of connections permitted per Exegy Ticker Plant. Note that SessionTickerMonitoring instances do not count against the maximum number of connections permitted.
In case of a disconnect, do not attempt to reestablish a session, clear slots, or resubscribe. (The Exegy API automatically handles reconnection and re-subscription to all previously subscribed-to instruments, including any subscription requests pending at the time of the disconnect.) If the user attempts to reestablish the session, clear slots or re-subscribe while XCAPI is automatically performing the same process, a variety of problems may occur, up to and including an abnormal exit of the client application. Please see "Client Disconnects" (under the "XCAPI Overview" menu) for detailed information on XCAPI's disconnect and failover logic.
Restrictions:
Parameters:
Returns:
An xerr type indicating the status of the creation operation.
Common error codes:
XINVAL Invalid parameter, object not created.
XCONNREFUSED Connection refused.
XCONNRESET Connection reset by peer.
XADDR Connection failed due to bad address or host name.
XSOCKET Unable to connect to specified socket.
XLOGINFAILED Connection refused due to incorrect login credentials.
XSLOWCONSUMER Client was disconnected because it is a slow consumer.
XPROTO Connection failed because client and appliance could not negotiate a connection.
XTIMEOUT Active connection timed out.
XTIME Connection request timed out waiting for server response.
XVERSION Connection refused due to version mismatch (between Exegy appliance and XC API).
XBADHANDLE Invalid handle.
XSUCCESS Connection and login to the Exegy appliance were successful.
XCONNLIMIT Connection limit reached.