The SetAuthorizationDetailsEx function allows you to directly set the state of an Authorization Definition in the currently loaded license - without entering an Activation Code. Call this function to set a definitions activated field to true or false, to set a parameter value and to set a stored Serial Number.  If you set the definitions activated state to true, the action which is associated with the definition is also executed.

Syntax

HRESULT SetAuthorizationDetailsEx ( long AuthorizationDefinitionID, BSTR AuthPassword, VARIANT_BOOL Activated, long ParameterValue, BSTR SerialNumber, long * return_code ) ;

Parameters

AuthorizationDefinitionID

[IN] This is a numeric value corresponding to the Authorization Definition ID of the currently loaded license that you wish to set the details for.

 

AuthPassword 

[IN] Wide character string. The local password of the Authorization Definition corresponding to the Authorization Definition ID in the first parameter. NOTE: This is the Local Authorization Definition Password specific to that definition - not the Global Authorization Definition Password.

 

Activated 

[IN] This is a boolean value indicating if the code is to be activated or not. See remarks below regarding behaviour.

 

ParameterReceived

[IN] This is a numeric value which the corresponding Authorization Definitions parameter value will be set to after the call.

 

StoredSerialNumber

[IN] This is a string value which the corresponding Authorization Definitions stored Serial Number will be set to after the call.

 

return_code

[OUT] This is (a pointer to) a numeric value that returns with a RETURNCODE that identifies the outcome of the operation. (See remarks section below for details.)

Remarks

Note: This function is illustrated in the SoftwareShield Flowcharts - (see flow chart #2).

When SetAuthorizationDetailsEx is successfully called, if you pass true in the Activated parameter, the corresponding definition is "activated".  This involves not only setting the definitions activated field to true, but also executing any and all behaviour associated with that type of definition. The one exception to this is if SetAuthorizationDetails is called on a Deactivation Authorization Definition (see below).

If the license has not been initialized successfully with a call to StartUp, the function will return with return_code holding FALSE_LICENSE_NOT_INITIALIZED.

If the AuthorizationCodeID is not between 0 and 63, the function will return with the return_code holding FALSE_CODE_OUT_OF_RANGE.

If the AuthorizationCodeID is in range, but the ID is not valid for the license, the function will return with the return_code holding FALSE_CODE_INVALID_BAD_ID.

If the AuthorizationCodeID is valid for the license but the password passed was not an exact case-sensitive match, the function will return with the return_code holding FALSE_CODE_INVALID_PASSWORD.

If the AuthorizationCodeID corresponds to a Deactivation Authorization Definition, the function will return with the return_code holding FALSE_DEACTIVATION_ID_ONLY.

Otherwise, the corresponding Authorization Definition will be set to the new values passed.  If the Activated parameter is true, the behaviour associated with the definition will also be executed. Note that while you can set the Activated parameter to false to set the definitions activated field to false - no behaviour or action is executed that would (for example) reverse a previous activation. The stored Serial Number will be set to the value passed. Note that the Serial Number is not validated for format or is it validated against a CheckPoint server.

You should use this function (as a rule of thumb) only to set the details of a General Use Authorization Definition.  Although, if needed, it can be called on other definitions types as well.  We recommend that if you do call it on other types, ensure you do not call it on types which require a date parameter, since that parameter is in an encoded format which is not available to your applications.

Return Value

As with all COM function calls they return an HRESULT. HRESULT is a data type that is a 32-bit error or warning code. Check your compilers documentation for information on interpreting the HRESULT value.

Function Information

Exposed By Interface:	"ISSCProtector"
Exposed In COM Server Binaries:	"SSCProt.dll" and "SSCProtD.dll"