PrlSrv_Login Function

Performs a remote login operation using the specified parameters.

Syntax

PRL_HANDLE PrlSrv_Login(
    PRL_HANDLE hServer, 
    PRL_CONST_STR host, 
    PRL_CONST_STR user, 
    PRL_CONST_STR passwd, 
    PRL_CONST_STR sPrevSessionUuid, 
    PRL_UINT32 port_cmd, 
    PRL_UINT32 timeout, 
    PRL_SECURITY_LEVEL security_level
);

File

PrlApiDisp.h

Parameters

hServer

A handle of type PHT_SERVER identifying the Virtuozzo Service.

host

The name or IP address of the host machine (a UTF-8 encoded, null-terminated string).

user

User name (a UTF-8 encoded, null-terminated string).

passwd

Password (a UTF-8 encoded, null-terminated string).

sPrevSessionUuid

Previous session ID. This is an optional parameter that can be used in recovering from a lost Virtuozzo Service connection. The ID will be used to restore references to the tasks that were initiated in the previous session and are still running inside the Virtuozzo Service. You can pass a null or an empty string value if you are not restoring any references. See PrlSrv_AttachToLostTask for more information.

port_cmd

Port number. Pass 0 (zero) to use the default port.

timeout

Timeout value in milliseconds. The operation will be automatically interrupted if a connection is not established within this timeframe. Specify 0 (zero) for infinite timeout.

security_level

Communication security level to use for this connection. The security level set here will be used for all communications with the Virtuozzo Service for the duration of this session. The minimum allowable security level can be determined using the PrlDispCfg_GetMinSecurityLevel function.

flags

A bitset of flags. Allowed next values:

0 - no flags. It's behaviour by default ( as PrlSrv_Login() )

PACF_NON_INTERACTIVE_MODE

to use non-interactive mode. In interactive mode, a client may receive questions from the Virtuozzo Service, which it is expected to answer in order for the operation to continue. In non-interactive mode, the Virtuozzo Service will make decisions on its own.

Returns

A handle of type PHT_JOB containing the results of this asynchronous operation, including the return code and a handle of type PHT_LOGIN_RESPONSE, containing an additional Virtuozzo Service information.

PRL_INVALID_HANDLE if there's not enough memory to instantiate the job object.

Remarks

A remote login operation logs the user to a Virtuozzo Service running on a remote host. You can also use this function to log to a local host or you can use the PrlSrv_LoginLocal function, which is a simplified version created specifically to perform local host logins.

To get the return code from the PHT_JOB object, use the PrlJob_GetRetCode function. Possible values are:

PRL_ERR_INVALID_ARG - invalid handle was passed.

PRL_ERR_SUCCESS - function completed successfully.

To get the results from the PHT_JOB object:

Use the PrlJob_GetResult function to obtain a handle to the PHT_RESULT object.
Use the PrlResult_GetParam function to obtain a handle of type PHT_LOGIN_RESPONSE.

See Also

PrlDispCfg_GetMinSecurityLevel

Example

The following is a complete sample program that illustrates how to log in to a remote Virtuozzo Service.

#include "Parallels.h"
#include "Wrappers/SdkWrap/SdkWrap.h"
#include <stdio.h>

#ifdef _WIN_
#include <windows.h>
#else
#include <unistd.h>
#endif

const char *szVmName = "Windows XP";
const char *szServer = "127.0.0.1";
const char *szUsername = "SomeUserName";
const char *szPassword = "SomePassword";

int main( int argc, char* argv[] )
{
    PRL_HANDLE hServer;
    PRL_RESULT ret;

    // Use the correct dynamic library depending on the platform.
    #ifdef _WIN_
    #define SDK_LIB_NAME "prl_sdk.dll"
    #elif defined(_LIN_)
    #define SDK_LIB_NAME "libprl_sdk.so"
    #elif defined(_MAC_)
    #define SDK_LIB_NAME "libprl_sdk.dylib"
    #endif

    // Load the SDK library.
    if ( PRL_FAILED( SdkWrap_Load( SDK_LIB_NAME ) ) &&
        PRL_FAILED( SdkWrap_Load( "./" SDK_LIB_NAME ) ) )
    {
        fprintf( stderr, "Failed to load " SDK_LIB_NAME "\n" );
        return -1;
    }

    // Initialize the API.
    ret = PrlApi_Init( PARALLELS_API_VER );
    if ( PRL_FAILED( ret ) )
    {
        fprintf( stderr, "PrlApi_Init returned with error: %s.\n",
            PRL_RESULT_TO_STRING( ret ) );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return ret;
    }

    // Create a server handle.
    ret = PrlSrv_Create( &hServer );
    if ( PRL_FAILED( ret ) )
    {
        fprintf( stderr, "PrlSvr_Create failed, error: %s",
            PRL_RESULT_TO_STRING( ret ) );
        PrlHandle_Free( hServer );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return -1;
    }

    // Log in (asynchronous call).
    PRL_HANDLE hJob = PrlSrv_Login(
            hServer,            // PRL_HANDLE of type PHT_SERVER.
            szServer,           // Name and IP address of the host machine.
            szUsername,         // User name.
            szPassword,         // Password.
            0,                  // Previuos session ID (0 if not used).
            0,                  // Port number (0 for default port).
            0,                  // Timeout value (0 for default timeout).
            PSL_LOW_SECURITY ); // Security level.

    // Wait for a maximum of 10 seconds for
    // the job to complete.
    ret = PrlJob_Wait( hJob, 1000 );
    if ( PRL_FAILED( ret ) )
    {
        fprintf( stderr, "PrlJob_Wait for PrlSrv_Login returned with error: %s\n",
            PRL_RESULT_TO_STRING( ret) );
        PrlHandle_Free( hJob );
        PrlHandle_Free( hServer );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return -1;
    }

    // Analyze the result of PrlSrv_Login.
    PRL_RESULT nJobResult;
    ret = PrlJob_GetRetCode( hJob, &nJobResult );
    if ( PRL_FAILED( nJobResult ) )
    {
        PrlHandle_Free( hJob );
        PrlHandle_Free( hServer );
        printf( "Login job returned with error: %s\n",
            PRL_RESULT_TO_STRING( nJobResult ) );
        PrlHandle_Free( hJob );
        PrlHandle_Free( hServer );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return -1;
    }
    else
        printf( "Login was successful.\n" );

    // Log off.
    hJob = PrlSrv_Logoff( hServer );
    ret = PrlJob_Wait( hJob, 1000 );
    if ( PRL_FAILED( ret ) )
    {
        fprintf( stderr, "PrlJob_Wait for PrlSrv_Logoff returned error: %s\n",
            PRL_RESULT_TO_STRING( ret ) );
        PrlHandle_Free( hVm );
        PrlHandle_Free( hJob );
        PrlHandle_Free( hServer );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return -1;
    }

    ret = PrlJob_GetRetCode( hJob, &nJobResult );
    if ( PRL_FAILED( ret ) )
    {
        fprintf( stderr, "PrlJob_GetRetCode failed for PrlSrv_Logoff with error: %s\n",
            PRL_RESULT_TO_STRING( ret ) );
        PrlHandle_Free( hVm );
        PrlHandle_Free( hJob );
        PrlHandle_Free( hServer );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return -1;
    }

    // Report success or failure of PrlSrv_Logoff.
    if ( PRL_FAILED( nJobResult ) )
    {
        fprintf( stderr, "PrlSrv_Logoff failed with error: %s\n",
            PRL_RESULT_TO_STRING( nJobResult ) );
        PrlHandle_Free( hVm );
        PrlHandle_Free( hJob );
        PrlHandle_Free( hServer );
        PrlApi_Deinit();
        SdkWrap_Unload();
        return -1;
    }
    else
        printf( "Logoff was successful.\n" );

    // Free handles that are no longer required.
    PrlHandle_Free( hVm );
    PrlHandle_Free( hJob );
    PrlHandle_Free( hServer );

    // De-initialize the Virtuozzo API, and unload the SDK.
    PrlApi_Deinit();
    SdkWrap_Unload();

    printf( "\n\nEnd of program.\n\n" );
    char c;
    scanf( &c, "%c" );

    return 0;
}

Links

PHT_SERVER, Example, See Also