[[PageOutline]]
= Client setup logic for Windows =

There are three install types supported by the 5.x generation of BOINC clients. 

== Single-User Install ==

Single user installs are the most basic and least prone to failure form of BOINC client installation.

It has the following properties:
|| File Layout:      || [wiki:ClientSetupLogicWinFileLayout Standard File Layout] ||
|| File Permissions: || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] %USERNAME% (Full Control) ||
|| Launch Mechinism: || Shortcut to boincmgr.exe in the user's 'Startup' folder ||

== Shared Install ==

Shared installs are geared towards computers who have multiple user accounts and fast user switching is enabled. The first person to login launches BOINC and all the science applications. If the first person logs out BOINC is shutdown. 

It has the following properties:
|| File Layout:      || [wiki:ClientSetupLogicWinFileLayout Standard File Layout] ||
|| File Permissions: || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] Users (Full Control) ||
|| Launch Mechinism: || Shortcut to boincmgr.exe in the all-users 'Startup' folder ||

== Service-Mode Install ==

Service-Mode installs allows BOINC to run even when nobody is logged into the system. When Windows boots up, it'll launch BOINC. An existing user account must be specified to execute BOINC with at startup. This user account will be granted the 'Execute as a Service' user right during the installation process if it doesn't already have it.

It has the following properties:
|| File Layout:      || [wiki:ClientSetupLogicWinFileLayout Standard File Layout] ||
|| File Permissions: || SYSTEM (Full Control) [[BR]] Administrators (Full Control) [[BR]] %SERVICE_USERNAME% (Full Control) [[BR]] %USERNAME% (Modify, Read & Execute, List Folder Contents, Read, Write)||
|| Launch Mechinism: || Shortcut to boincmgr.exe in the user's 'Startup' folder [[BR]] BOINC will be launched at boot by the Service Control Manager ||

== Install Details ==

Installer packages based on the Microsoft Installer technology are divided into two phases. Phase one is the 'User Interface' phase where the installer presents all the questions that need to be answered before a successful installation can occur. Phase two is the 'Execution' phase where the actual installation occurs.

Both phases are broken up into a sequence which executes custom actions in a specific order. Each custom action, whether defined by the MSI system or the setup programmer, preforms a specific action.

The following custom actions were designed specifically for BOINC:

=== CARestoreSetupState ===

Restore the previous setup parameters from the registry.

Registry location: HKLM\Software\Space Sciences Laboratory, U.C. Berkeley\BOINC Setup

|| Execution After:     || ISSetupFilesExtract ||
|| Execution Condition: || ||

Pseudocode:
{{{
GetRegistryValue( "INSTALLDIR", strInstallDirectory );
GetRegistryValue( "SETUPTYPE", strSetupType );
GetRegistryValue( "LAUNCHPROGRAM", strLaunchProgram );
GetRegistryValue( "ENABLELAUNCHATLOGON", strEnableLaunchAtLogon );
GetRegistryValue( "ENABLESCREENSAVER", strEnableScreensaver );
GetRegistryValue( "SERVICE_DOMAIN", strServiceDomain );
GetRegistryValue( "SERVICE_USERNAME", strServiceUsername );

SET INSTALLDIR TO strInstallDirectory
SET SETUPTYPE TO strSetupType
SET LAUNCHPROGRAM TO strLaunchProgram
SET ENABLELAUNCHATLOGON TO strEnableLaunchAtLogon
SET ENABLESCREENSAVER TO strEnableScreensaver
SET SERVICE_DOMAIN TO strServiceDomain
SET SERVICE_USERNAME TO strServiceUsername

RETURN SUCCESS
}}}

=== CASaveSetupState ===

Save the current setup parameters to the registry.

Registry location: HKLM\Software\Space Sciences Laboratory, U.C. Berkeley\BOINC Setup

|| Execution After:     || !ExecuteAction ||
|| Execution Condition: || ||

Pseudocode:
{{{
GET INSTALLDIR STORE strInstallDirectory
GET SETUPTYPE STORE strSetupType
GET LAUNCHPROGRAM STORE strLaunchProgram
GET ENABLELAUNCHATLOGON STORE strEnableLaunchAtLogon
GET ENABLESCREENSAVER STORE strEnableScreensaver
GET SERVICE_DOMAIN STORE strServiceDomain
GET SERVICE_USERNAME STORE strServiceUsername

SetRegistryValue( "INSTALLDIR", strInstallDirectory );
SetRegistryValue( "SETUPTYPE", strSetupType );
SetRegistryValue( "LAUNCHPROGRAM", strLaunchProgram );
SetRegistryValue( "ENABLELAUNCHATLOGON", strEnableLaunchAtLogon );
SetRegistryValue( "ENABLESCREENSAVER", strEnableScreensaver );
SetRegistryValue( "SERVICE_DOMAIN", strServiceDomain );
SetRegistryValue( "SERVICE_USERNAME", strServiceUsername );
SetRegistryValue( "SETUPSTATESTORED", strSetupStateStored );

RETURN SUCCESS
}}}

=== CAValidateSetupType ===

The Microsoft Installer technology allows you to install a package without using the 'User Interface', so this custom action validates the input passed to the execution phase.

|| Execution After:     || ValidateProductID ||
|| Execution Condition: || ||

Pseudocode:
{{{
IF SetupType IS NOT NULL
    IF (SetupType IS 'Single') OR (SetupType IS 'Service')
        IF (AllUsers IS NOT NULL) OR (IsAdminPagage IS '1')
            RETURN ERROR
        END IF
    ELSE
        IF (AllUsers IS '1')
            RETURN ERROR
        END IF
    END IF
END IF

RETURN SUCCESS
}}}

=== CAValidateServiceAccount ===

Validates the service parameters passed to the execution phase.

|| Execution After:     || CAValidateSetupType ||
|| Execution Condition: || VersionNT AND (SETUPTYPE = "Service OR SETUPTYPE = "ServiceGUI") ||

Pseudocode:
{{{
IF ServicePassword IS NULL
    IF (ServiceDomainUsername IS NOT 'LOCALSYSTEM') AND (ServiceDomainUsername IS NOT 'NetworkService')
        RETURN ERROR
    END IF
END IF

IF ServiceDomainUsername IS NULL
    IF (ServiceDomain IS NULL) OR (ServiceUsername IS NULL)
        RETURN ERROR
    END IF
ELSE
    SET ServiceDomain TO "Domain portion of ServiceDomainUsername"
    SET ServiceUsername TO "Username portion of ServiceDomainUsername"
END IF

RETURN SUCCESS
}}}

=== CAShutdownBOINC ===

Gracefully shutdown BOINC if it is running, if that fails terminate it.

|| Execution After:     || CAValidateServiceAccount ||
|| Execution Condition: || VersionNT AND NOT INSTALLED ||

Pseudocode:
{{{
IF BOINCIsRunning() = TRUE
    ShutdownBOINC()
END IF
TerminateBOINC()

RETURN SUCCESS
}}}

=== CAShutdownBOINCManager ===

Gracefully shutdown BOINC Manager if it is running, if that fails terminate it.

|| Execution After:     || CAShutdownBOINC ||
|| Execution Condition: || VersionNT AND NOT INSTALLED ||

Pseudocode:
{{{
IF BOINCManagerIsRunning() = TRUE
    ShutdownBOINCManager()
END IF
TerminateBOINCManager()

RETURN SUCCESS
}}}

=== CAShutdownBOINCManager95 ===

Gracefully shutdown BOINC Manager if it is running, if that fails terminate it.

|| Execution After:     || CAShutdownBOINCManager ||
|| Execution Condition: || Version95 AND NOT INSTALLED ||

Pseudocode:
{{{
IF BOINCManagerIsRunning() = TRUE
    ShutdownBOINCManager()
END IF
TerminateBOINCManager()

RETURN SUCCESS
}}}

=== CAShutdownBOINCScreensaver ===

Gracefully shutdown BOINC Screensaver if it is running, if that fails terminate it.

|| Execution After:     || CAShutdownBOINCManager95 ||
|| Execution Condition: || VersionNT AND NOT INSTALLED ||

Pseudocode:
{{{
IF BOINCScreensaverIsRunning() = TRUE
    ShutdownBOINCScreensaver()
END IF
TerminateBOINCScreensaver()

RETURN SUCCESS
}}}

=== CAMigratex86x64 ===

Migrate BOINC Data from the 32-bit application storage location to the 64-bit application storage location.

|| Execution After:     || CAShutdownBOINCScreensaver ||
|| Execution Condition: || ||

Pseudocode:
{{{
MoveFileEx(
    "C:\Program Files (x86)\BOINC",
    InstallDir,
    MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH
)

RETURN SUCCESS
}}}

=== CAMigrateCPDNBBC ===

Migrate the CPDNBBC data from the specialized CPDNBBC directory to the standard BOINC installation directory.

|| Execution After:     || CAMigratex86x64 ||
|| Execution Condition: || ||

Pseudocode:
{{{
MoveFileEx(
    "C:\Program Files\Climate Change Experiment",
    InstallDir,
    MOVEFILE_COPY_ALLOWED|MOVEFILE_WRITE_THROUGH
)

RETURN SUCCESS
}}}

=== CACleanupOldBinaries ===

After uninstalling any older versions of BOINC, make sure all BOINC related binaries have been deleted from the system.

|| Execution After:     || CAMigrateCPDNBBC ||
|| Execution Condition: || ||

Pseudocode:
{{{
DeleteFile(InstallDir + "\boinc.exe");
DeleteFile(InstallDir + "\boincmgr.exe");
DeleteFile(InstallDir + "\boinccmd.exe");
DeleteFile(InstallDir + "\boinc.dll");
DeleteFile(InstallDir + "\libcurl.dll");
DeleteFile(InstallDir + "\libeay32.dll");
DeleteFile(InstallDir + "\ssleay32.dll");
DeleteFile(InstallDir + "\zlib1.dll");
DeleteFile(InstallDir + "\dbghelp.dll");
DeleteFile(InstallDir + "\dbghelp95.dll");
DeleteFile(InstallDir + "\srcsrv.dll");
DeleteFile(InstallDir + "\symsrv.dll");

RETURN SUCCESS
}}}

=== CAGrantServiceExecutionRight ===

Make sure the service user account is allowed to execute services.

|| Execution After:     || !InstallInitialize ||
|| Execution Condition: || VersionNT And (SETUPTYPE = "Service" Or SETUPTYPE = "ServiceGUI") And SERVICE_GRANTEXECUTIONRIGHT = "1" ||

Pseudocode:
{{{
pSID = GetAccountSid(ServiceDomainUsername)
SetPrivilegeOnAccount(
    pSID,
    "SeServiceLogonRight",
    TRUE
)

RETURN SUCCESS
}}}

=== CAGetAdministratorsGroupName ===

Convert the well known group SID into the human readable localized version of the name.

|| Execution After:     || CAGrantServiceExecutionRight ||
|| Execution Condition: || VersionNT ||

Pseudocode:
{{{
GroupName = LookupAliasFromRid(NULL, DOMAIN_ALIAS_RID_ADMINS)
SET GROUPALIAS_ADMINISTRATORS TO GroupName


RETURN SUCCESS
}}}

=== CAGetUsersGroupName ===

Convert the well known group SID into the human readable localized version of the name.

|| Execution After:     || CAGetAdministratorsGroupName ||
|| Execution Condition: || VersionNT ||

Pseudocode:
{{{
GroupName = LookupAliasFromRid(NULL, DOMAIN_ALIAS_RID_USERS)
SET GROUPALIAS_USERS TO GroupName


RETURN SUCCESS
}}}