3.1.5.4 GetCookie

  • Article

Synopsis:

This method is called by the client during the initial dialog between the client and the server. It MUST be called after GetConfig (section 3.1.5.2) and GetAuthorizationCookie (section 3.1.5.3), but before calling any other operation. The cookie returned by the method MUST be passed to all subsequent operations in the client Web service. The client SHOULD cache the cookie and call this method only to renew the cached cookie, either because the cookie expired or because the server has thrown a SoapFault with one of the following ErrorCodes: InvalidCookie, ServerChanged, ConfigChanged, or CookieExpired. If this method is called in response to one of these errors, it MUST be called in the sequence specified for the error in section 2.2.2.4.

Request Validation:

Parameter

Validation Conditions

Error Code

authCookies

MUST contain exactly one Authorization Cookie—the one returned from GetAuthorizationCookie (section 3.1.5.3).

InvalidAuthorizationCookie

oldCookie

MUST either be NULL or contain a valid cookie issued by this server (typically an expired cookie).

InvalidCookie or ServerChanged

lastChange

MUST be the same as the last time the configuration changed on the server (although this check can be done in SyncUpdates (section 3.1.5.7) instead).

ConfigChanged

protocolVersion

SHOULD be a non-NULL two-part version string (for example, "1.0").

InvalidParameters

Data Processing:

The returned cookie SHOULD contain opaque authorization, authentication, and state information for use by the server. This information can include the following:

  • Client identity and target group membership (as extracted from the cookie returned by the SimpleAuth Web service).

  • Cookie expiration time (enabling the server to determine whether the cookie has expired).

  • Server identity (enabling the server to verify that it issued the cookie).

  • Client protocol version (enabling the server to implement version-specific behavior).

  • Configuration "lastChange" time (enabling the server to determine whether to force the client to call GetConfig (section 3.1.5.2) again).

  • The client's last synchronization time.

The server SHOULD copy state information from the oldCookie element to the new cookie it returns from this method, providing the oldCookie was obtained from the same server. Alternatively, the client MAY disregard the oldCookie's state information and generate new state information as if the client had passed an oldCookie value of NULL.

Results:

If no faults occur during the operation, the server MUST return a GetCookieResponse message to the client.