How to use the new Site Streaming feature

Article:HOWTO74595  |  Created: 2012-03-14  |  Updated: 2012-03-16  |  Article URL http://www.symantec.com/docs/HOWTO74595
Article Type
How To


Subject


 

About Site Streaming
The Site Streaming feature provides a reliable and automated local virtual software deployment for branch or satellite offices that may have low bandwidth. This new feature allows third party software to integrate with the Streaming agent to   better optimize Streaming locations. Once Site Streaming is set up, Workspace Streaming first checks for applications and dependencies on local branch endpoints. If possible, streaming queries are resolved locally before using an external application repository at the corporate data center.
Use the following APIs to set up the necessary queries to interface with Streaming.
  • Cache check
The Cache Check API provides a way to query if a package is already present on the endpoint.
 
This API already exists on the IAppStreamReporting interface:
 [id(201), helpstring("Get Package General Information")]
 HRESULT getPackageInfo([in] BSTR bsPackageUID,
                                   [out] BSTR* bsPackageName,
                                   [out] BSTR* bsPackageVendor,
                                  [out] long* plLastUsed,
                                   [out, retval] long* plStatus);
BSTR bsPackageUID - This is the package identifier. It should be of the form {PKGGUID.EN_US}_{VERSION.EN_US}, although just a pkgGUID will work as it will query the server for the current default version of the package.
BSTR* bsPackageName - The name of the package if it exists.
BSTR* bsPackageVendor - The name of the package vendor if the package is in the cache.
long* plLastUsed - The last used timestamp (epoch - seconds since Jan 1, 1970) of the package if it exists in the cache.
long* plStatus - long* plStatus - A windows error code indicating if the package is in the cache. Possible return values are ERROR_SUCCESS (0), or ERROR_FILE_NOT_FOUND (2).
  • Version on Server and Package in use check
The version/package in use check provides a way to ask the SWS client if it is currently possible to upgrade the package based on the provided package identifier. When intercepting an upgrade request, the SWS client can be asked if the package (version) is already in use, if it is, it will not be available for upgrade and the existing version of the package will be used on the next launch.
Added to the IAppStreamPackageOperations interface the following method:
 
            [id(102), helpstring("Is Package In Use")]
HRESULT isPackageInUse([in] BSTR bsPackageUID, [out, retval] VARIANT_BOOL *pvbInUse);
 
BSTR bsPackageUID - This is the package identifier. It should be of the form {PKGGUID.EN_US}_{VERSION.EN_US}, although just a pkgGUID will work as it will use the version currently on the system.
BARIANT_BOOL *pvbInUse - return value, returns TRUE if there is an active session running for the package.
 
In order to discover the latest version available from the server for a user, the folloing call has been added to the IAppStreamPackageOperations interface:
 
            [id(103), helpstring("Package Server Version")]
            HRESULT getServerPackageVersion([in] BSTR bsPackageUID,
                                            [in, out] BSTR* pbsServerURL,
                                            [in, out] BSTR* pbsUserName,
                                            [out] long* plVersion,
                                            [out, retval] long* plStatus);
 
BSTR bsPackageUID - This is the package identifier. It should be of the form {PKGGUID.EN_US}_{VERSION.EN_US}, although just a pkgGUID will work as it will query the server for the current default version of the package.
BSTR* pbsServerURL - The URL of the FE to query for information on package dependencies and user provisions. If left blank, the primary server URL will be used. On output this will be set to the URL of the server queried. This is useful in case the API caller does not know the current default server URL.
BSTR* pbsUserName - The username to use in the provision query. If left blank, the current user in the HKLM\Software\AppStream\AppMgr\Apps\Licenses:AppStreamUser will be used. On output this will be set to the username used in the query. This is useful in case the API caller does not know the current default server URL.
long* plVersion - The highest version number of the package that the server currently has provisioned for the user.
long* plStatus - An EngineInterface::ErrCode enumeration value. See Appendix A for the value meanings. Possible return values include (but are not limited to):
INVALID_DATA (21) - bad package identifier
NO_RESPONSE (2) - failed to contact specified or default primary server
COULD_NOT_MAKE_OPERATION (4) - user is not provisioned for this package (version).
SEND_FAILED (16) - could not send the provision request to the server or no valid response was received.
Note that this information is based on the provision information returned by the server. If the user is provisioned for the package, but the package does not match the other criteria for the provision request (wrong OS version, wrong OS architecture (x86 vs. x64)), the server version will be 0 and an error COULD_NOT_MAKE_OPERATION will be returned.
 
  • Dependency determination
The Dependency determination API provides a way to query for package dependencies so that all packages can be downloaded at once, allowing the installation of the top level package to succeed or proceed quicker.
Added to the IAppStreamPackageOperations interface the following method:
 
            [id(104), helpstring("Package Dependencies")]
            HRESULT getPackageDependencies([in] BSTR bsPackageUID,
                                           [in] long lDependencyLevels,
                                           [in, out] BSTR* pbsServerURL,
                                           [in, out] BSTR* pbsUserName,
                                           [out] SAFEARRAY(BSTR)* absDependentPackageUIDs,
                                           [out, retval] long* plStatus);
 
BSTR bsPackageUID - This is the package identifier. It should be of the form {PKGGUID.EN_US}_{VERSION.EN_US}, although just a pkgGUID will work as it will query the server for the current default version of the package.
lDependencyLevels - An integer specifying the limit of how many dependency levels to pursue. A value of 0 means all dependency levels will be searched.
An example:
PackageA is dependent on PackageB
PackageB is dependent on PackageC and PackageD
PackageC is dependent on PackageX
PackageD is dependent on PackageA (circular dependency loop)
PackageX is dependent on PackageC (direct circular dependency)
 
A dependency level of 1 for PackageA will report just PackageB.
A dependency level of 2 for PackageA will report PackageB, PackageC, and PackageD
A dependency level of 3 for PackageA will report PackageB, PackageC, PackageD, and PackageX. PackageA is not included as the dependency logic checking will remove the top level package (PackageA) from the results.
A dependency level of 4 for PackageA will report PackageB, PackageC, PackageD, and PackageX. PackageA is not included as above. PackageC is not listed twice unless different explicit versions are in the dependency entries.
A dependency level of 0 for PackageA will report PackageB, PackageC, PackageD, and PackageX.
 
 
BSTR* pbsServerURL - The URL of the FE to query for information on package dependencies and user provisions. If left blank, the primary server URL will be used. On output this will be set to the URL of the server queried.
 
BSTR* pbsUserName - The username to use in the provision query. If left blank, the current user in the HKLM\Software\AppStream\AppMgr\Apps\Licenses:AppStreamUser will be used. On output this will be set to the username used in the query.
 
SAFEARRAY(BSTR)* absDependentPackageUIDs - The flattened list of packages that the top level package is dependent on. These will be in the format of {PKGGUID.EN_US}_{VERSION.EN_US}.
 
long* plStatus - An EngineInterface::ErrCode enumeration value, see Appendix A.
           
                       
 
  • Client Repository location database manipulation interface
This API exposes an interface that allows external scripts or processes to manipulate the client's package repository list for a package.
[
   object,
  uuid(2D26DBF0-D240-485F-A4CF-0280D456FDA0),
  dual,
  helpstring("IAppStreamPackageRepositoryManiuplator Interface"),
  pointer_default(unique)
]
interface IAppStreamPackageRepositoryManipulator : IDispatch
{

   RepositorySourceType (long)
    0 - Primary location - Will be placed in front of server provided
                            locations.
     1 - Server provided  - Repository Source provided by the server,
cannot use this type in the Add or Remove Repository.
     2 - Primary backup   - Will be placed in between the first repository                                 location provided by the server and all of the                          rest of the repository locations provided by
    the server.
     3 - Backup           - Will be placed at the end of all other known
                            repositories.

    [id(100), helpstring("Get Repositories")]
    HRESULT getRepositories([in] BSTR bsPackageUID,
                            [out] SAFEARRAY(BSTR)* absRepositoryLocations,
                            [out] SAFEARRAY(long)* alRepositorySourceType,
                            [out, retval] long* plStatus);

    [id(101), helpstring("Add Repository")]
    HRESULT addRepository([in] BSTR bsPackageUID,
                          [in] BSTR bsRepositoryLocation,
                          [in] long lRepositorySourceType,
                          [out, retval] long* plStatus);

    [id(102), helpstring("Remove Repository")]
    HRESULT removeRepository([in] BSTR bsPackageUID,
                             [in] BSTR bsRepositoryLocation,
                             [in] long lRepositorySourceType,
                             [out, retval] long* plStatus);

    [id(103), helpstring("Remove All Repositories")]
    HRESULT removeAllRepositories([in] BSTR bsPackageUID,
                                  [in] VARIANT_BOOL vbAllSourceTypes,
                                  [in] long lRepositorySourceType,
                                  [out, retval] long* plStatus);

};



[
  object,
  uuid(707B5333-2063-433A-B7D5-70A4BDCBA9B5),
  dual,
  helpstring("IAppStreamProvisionOperations Interface"),
  pointer_default(unique)
]
interface IAppStreamProvisionOperations : IDispatch
{
  [id(100), helpstring("Get Provisions")]
  HRESULT getUserProvisionedPackages([in, out] BSTR* pbsServerURL,
                                     [in, out] BSTR* pbsAppStreamUserName,
                                     [out] SAFEARRAY(BSTR)* pProvisionList,
                                     [out, retval] long* plStatus);

  [id(500), helpstring("Process provisions")]
  HRESULT processProvisions([out, retval] long* plStatus);
};



Package Repository Manipulator
    HRESULT getRepositories([in] BSTR bsPackageUID,
                            [out] SAFEARRAY(BSTR)* absRepositoryLocations,
                            [out] SAFEARRAY(long)* alRepositorySourceType,
                            [out, retval] long* plStatus);

This API retrieves the ordered list of repositories known for this package identifier.  Note that a package that is not currently in the cache can have known repositories; it just won't have any server provided repositories.

BSTR bsPackageUID - The package identifier to query.

SAFEARRAY(BSTR)* absRepositoryLocations - an array of strings representing the list of repositories in the order that the SWS client will attempt to use them should any be unreachable and/or not present.  There most certainly can be duplicates.

SAFEARRAY(long)* alRepositorySourceType - an array of types, this array will be the same size as the absRepositoryLocations array.  The type in the position in this array corresponds to the repository source type for the position in the absRepositoryLocations array.  If the package is in the cache, then the array will always be in the format of zero or more primary servers (repository type 0), followed by the first server provided location (repository type 10, followed by zero or more primary backup servers (repository type 2), followed by zero or more server provided locations. If the server provides more than one repository location, repository type 1, followed by zero or more backup repository locations (repository type 3).
Note that the repository location types are used to differentiate user supplied repositories. All repositories provided by the server, whether they come from repository rules or from backup servers, will be considered repository type 2 (server provided).

long* plStatus - An SWS return code.  0 = OK, see Appendix A for the full enumeration list of error values.

    HRESULT addRepository([in] BSTR bsPackageUID,
                          [in] BSTR bsRepositoryLocation,
                          [in] long lRepositorySourceType,
                          [out, retval] long* plStatus);

Adds a repository location for a package identifier.  This package does not have to be present in the cache for this operation.  Attempting to add a duplicate repository location in the same source type will be ignored, but you can add the same repository location to multiple source types.

BSTR bsPackageUID - The package identifier to modify the repository configuration.

BSTR bsRepositoryLocation - The repository location to add.  This can be a URL or a file.  Anything invalid will be tried during failover repository processing, so adding a bunch of garbage entries will just result in slowing down the connection to a valid repository.

long lRepositorySourceType - See the IDL above for an explanation of the source types.  Attempting to set a server provided source type (1) will be rejected with an INVALID_DATA (21) status.

long* plStatus - An SWS return code.  0 = OK, see Appendix A for the full enumeration list of error values.

    HRESULT removeRepository([in] BSTR bsPackageUID,
                             [in] BSTR bsRepositoryLocation,
                             [in] long lRepositorySourceType,
                             [out, retval] long* plStatus);

Removes a repository location for a package identifier.  This package does not have to be present in the cache for this operation.  However, you must have already added a repository location (via addRepository) previously in order for it to be removed.  Attempting to remove a location that is not already present in the list of repositories will not be remembered - it will not prevent the usage of that repository location should it be added later.

BSTR bsPackageUID - The package identifier to modify the repository configuration.

BSTR bsRepositoryLocation – This is the repository location to remove.  This can be a URL or a file. 

long lRepositorySourceType - See the IDL above for an explanation of the source types.  Attempting to set a server provided source type (1) will be rejected with an INVALID_DATA (21) status.

long* plStatus - An SWS return code.  0 = OK, see Appendix A for the full enumeration list of error values.  Attempting to remove a repository that wasn't present will result in success (0).

    HRESULT removeAllRepositories([in] BSTR bsPackageUID,
                                  [in] VARIANT_BOOL vbAllSourceTypes,
                                  [in] long lRepositorySourceType,
                                  [out, retval] long* plStatus);

Removes all known repositories, or all known repositories of a specific type depending on the request.

BSTR bsPackageUID - The package identifier to modify the repository configuration.

VARIANT_BOOL vbAllSourceTypes - If set to VARIANT_TRUE, all repositories across all types EXCEPT server provided repository locations will be removed.  If set to VARIANT_FALSE, the type in lRepositorySourceType will be used.

long lRepositorySourceType - See the IDL above for an explanation of the source types.  Attempting to use the server provided source type (1) will be rejected with an INVALID_DATA (21) status.

long* plStatus - An SWS return code.  0 = OK, see Appendix A for the full enumeration list of error values.  Attempting to remove a repository that wasn't present will result in success (0).

Provision Operations
 
HRESULT getUserProvisionedPackages([in, out] BSTR* pbsServerURL,
                                   [in, out] BSTR* pbsAppStreamUserName,
                                   [out] SAFEARRAY(BSTR)* pProvisionList,
                                   [out, retval] long* plStatus);

This function is similar to the query provisions feature on the AppMgrCmd command line tool ("AppMgrCmd -qp").  This method will only return the package identifiers rather than all of the information.

BSTR* pbsServerURL - The server to query.  If left blank, the current primary server will be used.  On output this will be set to the server that was queried.  If a server was provided and was valid, that will be returned, if this was blank, the URL of the primary server will be returned.

BSTR* pbsAppStreamUserName - The user name to use when querying provisions.  If left blank, this will use the last known user name, if integrated login is being used, the current windows user name will be used.  On output this will be set to the user name used to query provisions.

SAFEARRAY(BSTR)* pProvisionList - The list of package identifiers provisioned for this user at the server queried.  Note that the current OS can affect the returned list of provisions.

long* plStatus - An SWS return code.  0 = OK, see Appendix A for the full enumeration list of error values.


  HRESULT processProvisions([out, retval] long* plStatus);

This function is identical to the "check provisions now" feature on the AppMgrCmd command line tool ("AppMgrCmd -cpn").  The only return value is an SWS return code.  Unless the primary server isn't set or a user is not yet known, this will always return success as this is an asynchronous process.
 
 
Appendix A – EngineInterface error codes
            An EngineInterface::ErrCode enumeration value.
                        Enum ErrCode
                        {
OK = 0,
                        ENGINE_IS_DOWN,           // 1
                        NO_RESPONSE,              // 2
                        OPERATION_FAILED,         // 3
                        COULD_NOT_MAKE_OPERATION, // 4
                        NOT_ENOUGH_MEMORY,        // 5
                        BUSY_CACHE,               // 6
                        BUSY_PACKAGE,             // 7
                        SCRIPT_FAILED,            // 8
                        CANNOT_AUTHENTICATE,     // 9
                        UNKNOWN,                  // 10
                        NO_RUNNING_SESSION,       // 11
                        SERVER_FAILURE,           // 12
                        NO_BACKEND_CONNECTION,    // 13
                        BACKEND_FAILURE,          // 14
                        TRAINING_DISABLED,        // 15
                        SEND_FAILED,              // 16
                        UNINSTALL_FAILED,         // 17
                        PACKAGE_SHARED_FILES_NOT_COMPLETE, // 18
                        SVS_PACKAGE_PROCESS_OPEN, // 19
                        CANNOT_FIND_REQUEST,      // 20
                        INVALID_DATA,             // 21
                        CONTINUE_WITH_LAUNCH,     // 22
                        PACKAGE_GHOSTREG_NOT_COMPLETE, // 23
                        PACKAGE_DOWNGRADED,       // 24
                        GHOSTREG_OPERATIONS_PENDING, // 25
}
 
 


Article URL http://www.symantec.com/docs/HOWTO74595


Terms of use for this information are found in Legal Notices