AIDA_hRestoreStackRaw

The AIDA_hRestoreStackRaw function restores an AIDA stack formerly saved by AIDA_boSaveStack. AIDA_hRestoreStackRaw does not replace any values of parameters by values given in the environment (the replacement table is loaded and can be queried by AIDA_pastSetReplacementTable but will not be interpreted while restoring the stack). So AIDA_hRestoreStackRaw can be used to retrieve the default values of parameters of which the values normally would be replaced when restoring the stack with AIDA_hRestoreStack.

handle AIDA_hRestoreStackRaw(
  const xchar *xsFileName,
  xchar *xsComment,
  dword *pdwCommentBufferSize
  dword *pdwStackLevels
);

Parameters

xsFileName

Filename of the configuration file to be used. The filename has to be a valid name for the target operating system. It has to be passed without extension.

xsComment

Pointer to a buffer for a comment loaded from the configuration file.

pdwCommentBufferSize

Pointer to variable that contains the size of the buffer passed in xsComment.

pdwStackLevels

When this Pointer is not NULL, AIDA_hRestoreStackRaw will set the given variable to a bitmask that represents all levels of components loaded by the application when the stack was saved.

Return Values

AIDA_hRestoreStackRaw returns a handle for the restored stack. It will store the comment in xsComment and will set *pdwCommentBufferSize to the true size of the comment including the terminating '\0' character. xsComment will be terminated with a '\0' character in any case. When pdwCommentBufferSize ≥ size of xsComment buffer the comment stored in xsComment had been truncated. Comments are limited to a buffer size of AIDA_nMaxCommentBufferSize (see AIDA_boSaveStack).

If the function fails, the returned value is NULL. The application can retrieve the error code using AIDA_iGetError.

Even if the function succeeds an error code may be set. This happens when during the restoration of a stack a loaded component refuses one of the saved parameters to be set. Therefore it is recommended to check the error code even when the function returns a handle.

Remarks

This function is deprecated. Use AIDA_hRestoreStackEx instead.

Attention: Stack manipulation functions and component configuration functions may not be called simultaneously from different threads with the same handle or otherwise will cause unpredictable results.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Linux: Requires a kernel supporting ELF binaries.
  Header: Declared in bsk_aida.h, also requires portab.h.
  Import Library (Windows): Use BSK_AIDA.lib.

See Also

AIDA Overview, AIDA Stacks Licensing/Authentication Overview, AIDA Functions, AIDA_hsGetPlainErrMsgX, AIDA_vFreeErrMsgX, AIDA_hCreateStack, AIDA_hCreateStackEx, AIDA_boDeleteStack, AIDA_boSaveStack, AIDA_hRestoreStack, AIDA_hRestoreStackEx, AIDA_pastSetReplacementTable, AIDA_bAddToStack, AIDA_boRemoveFromStack, AIDA_xsComponentName