Click or drag to resize

Calling Methods

In order to call any methods from a Web Service, the request must be authenticated by attaching a cookie containing the FileHold Licensed Session Identifier (FHLSID). The cookie represents the identity and permissions of the user performing the operation.

The FHLSID is created by a special service called Session Manager, which is part of the User Role Manager. Unlike other services it doesn’t require passing a cookie, because it verifies the identity of the user in a different way.

FileHold uses the database to store local users and their securely hashed passwords. When a local FileHold user logs in, the Session Manager verifies the login and password in the database. When a domain user logs in, the Session Manager communicates directly with the appropriate domain controller to verify the identity of the user.

The Session Manager also verifies if the user has FileHold account enabled, whether the limit of Concurrent Access Licenses (CAL) for the server has been reached, etc. Finally a new session is created for the user and assigned a randomly generated globally unique identifier.

The FileHold service license determines the number of available Concurrent Access Licenses. Some of them are permanently assigned to users with guaranteed access to the system (for example, the system administrator). The remaining CALs are shared between all other users with an active FileHold account. Each user with an active session takes one slot from the pool of CALs. A user can have several active sessions with different client types, sharing one CAL slot. This makes it possible to use different client applications at the same time. When a new session is created, the previous session for the given user and client type is automatically terminated. All client types are reserved for exclusive use by FileHold except for the CustomClient. Anyone creating a custom application must use the CustomClient type. Failure to do so may result in incorrect operation of the system.

1// Login with FileHold user name and password
2SessionManager sessionManager = new SessionManager();
3Guid sessionId = sessionManager.StartSession( username, password, Client.CustomClient );

The client application should store the FHLSID obtained from the Session Manager. Forms applications can use a simple variable and web applications may create their own cookie for verifying the user’s identity. The application can also retrieve additional information associated with the session, such as the name of the user and the list of operations which the user is allowed to perform.

1// Get session information object for currently logged in user
2SessionInfo sessionInfo = sessionManager.GetSessionInfo( sessionId );

Since the URLs of the web services are hard-coded in the configuration file of the client application and sometimes it’s necessary to allow the user to specify server’s URL at runtime, it may be necessary to replace the default URL of each web reference:

1Uri absolutePath = new Uri( service.Url );
2Uri relativePath = new Uri( baseServerUrl ).MakeRelativeUri( absolutePath );
4string serviceUrl = serverUrl;
5if ( !serviceUrl.EndsWith( "/" ) )
6    serviceUrl += "/";
8serviceUrl += relativePath;
9service.Url = serviceUrl;

Note that this code works for web references compatible with .NET 2.0. A different method must be used in case of WCF service references.

In order to pass the session identifier to the Web Service, it must be set as a cookie named “FHLSID”:

 1// If the service does not have cookie container create one
 2if ( service.CookieContainer == null )
 3    service.CookieContainer = new CookieContainer();
 5// Get the URI for which the cookie is valid
 6Uri uri = new Uri( service.Url );
 7string domain = uri.Host;
 8// Create the cookie
 9Cookie cookie = new Cookie( "FHLSID", sessionInfo.SessionId, "/", domain );
10// Save the cookie for the service
11service.CookieContainer.Add( cookie );

The default timeout for the web service calls may be too short for some operations so it can be set to a longer value.

1service.Timeout = 18000;

By default the maximum allowed values are:

If longer timeouts are required, the execution timeout for these services must also be increased in their configuration files, because the shorter of the two timeouts (client and server side) will cause the operation to fail.