PrfCloseProfile: Difference between revisions

Latest revision as of 23:51, 10 December 2023

Call this function when you are done with a profile you have created with PrfOpenProfile. The Handle to an Initialization file (HINI) you pass to PrfCloseProfile will be then be invalid, and should not be used for any further API calls.

Syntax

PrfCloseProfile ( HINI hini )

Parameters

hini (HINI) - input: Handle to an initialization file to close. This is any valid handle returned by PrfOpenProfile(). Passing HINI_PROFILE, HINI_USERPROFILE, or HINI_SYSTEMPROFILE is not permitted.

Returns

bRC (BOOL) - return

This return value is always either:

TRUE: success
FALSE: Error occurred; If FALSE, you may use WinGetLastError() to find out what went wrong.; Possible errors PrfCloseProfile() may incur:

PMERR_INI_FILE_IS_SYS_OR_USER	0x1124	HINI_PROFILE, HINI_USER, HINI_USERPROFILE, HINI_SYSTEM, or HINI_SYSTEMPROFILE was specified. These profiles may not be closed by an application.
PMERR_INVALID_INI_FILE_HANDLE	0x1115	An invalid HINI was specified.

Include Info

#define INCL_WINSHELLDATA

or

#define INCL_WIN

or

#define INCL_PM
#include <os2.h>

Gotchas

Don't pass the system or user profile handles to this function. They are opened initially by the operating system, and can't be closed by an application.

Sample Code

/*
 * Assume for the sake of this example that there exists two functions,
 *   one named RestOfProgram(), which will contain everything after we
 *   get the profile opened, and WhineAboutErrors(), which displays an
 *   error message, and terminates the program.
 */

#define INCL_WIN
#include <os2.h>

int main(void)
{
    HAB hab;
    HINI hiniMyProfile;

    hab = WinInitialize(0);
    hiniMyProfile = PrfOpenProfile(hab, "MYPROF.INI");

    if (hiniMyProfile != NULLHANDLE)
        RestOfProgram(hiniMyProfile);
    else
        WhineAboutErrors("Couldn't open profile.");

    /* After RestOfProgram() returns, close the profile we are done with. */

    if (PrfCloseProfile(hiniMyProfile) == FALSE)
        WhineAboutErrors("Couldn't close profile.");

    return(0);
} /* main */

@@ Line 1: / Line 1: @@
-=== Syntax ===
+Call this function when you are done with a profile you have created with [[PrfOpenProfile]]. The Handle to an Initialization file (HINI) you pass to PrfCloseProfile will be then be invalid, and should not be used for any further API calls.
- bRC = PrfCloseProfile( ''hini'' );
+==Syntax==
+ PrfCloseProfile ( HINI ''hini'' )
 === Parameters ===
-HINI ''hini'' (input)
+;''hini'' ([[HINI]]) - input:Handle to an initialization file to close. This is any valid handle returned by PrfOpenProfile(). Passing HINI_PROFILE, HINI_USERPROFILE, or HINI_SYSTEMPROFILE is not permitted.
-Handle to an initialization file to close. This is any valid handle
-returned by PrfOpenProfile(). Passing HINI_PROFILE, HINI_USERPROFILE,
-or HINI_SYSTEMPROFILE is not permitted.
 === Returns ===
-  BOOL bRC
+;''bRC'' ([[BOOL]]) - return
+:This return value is always either:
-This return value is always either:
+:;TRUE
+::success
-{| border="1"
+:;FALSE
-|-
+::Error occurred
-|TRUE
+::If FALSE, you may use WinGetLastError() to find out what went wrong.
-|success
+::Possible errors PrfCloseProfile() may incur:
-|-
+{|class="wikitable"
-|FALSE
-|Error occurred
-|}
-If FALSE, you may use WinGetLastError() to find out what went wrong.
-Possible errors PrfCloseProfile() may incur:
-{| border="1"
 |-
 |PMERR_INI_FILE_IS_SYS_OR_USER
 |0x1124
-|HINI_PROFILE, HINI_USER, HINI_USERPROFILE, HINI_SYSTEM, or
+|HINI_PROFILE, HINI_USER, HINI_USERPROFILE, HINI_SYSTEM, or HINI_SYSTEMPROFILE was specified. These profiles may not be closed by an application.
-HINI_SYSTEMPROFILE was specified. These profiles may not be
-closed by an application.
 |-
 |PMERR_INVALID_INI_FILE_HANDLE
 |0x1115
 |An invalid HINI was specified.
 |}
 === Include Info ===
+ #define INCL_WINSHELLDATA
-  #define INCL_WINSHELLDATA
 or
-  #define INCL_WIN
+ #define INCL_WIN
 or
-  #define INCL_PM
+ #define INCL_PM
-  #include &lt.os2.h&gt.
+ #include <os2.h>
-=== Usage Explanation ===
-Call this function when you are done with a profile you have created with
-PrfOpenProfile. The Handle to an Initialization file (HINI) you pass to
-PrfCloseProfile will be then be invalid, and should not be used for any
-further API calls.
-=== Relevant Structures ===
-=== Gotchas ===
+==Gotchas==
+Don't pass the system or user profile handles to this function. They are opened initially by the operating system, and can't be closed by an application.
-Don't pass the system or user profile handles to this function. They are
-opened initially by the operating system, and can't be closed by an
-application.
 === Sample Code ===
 <pre>
 /*
   * Assume for the sake of this example that there exists two functions,
@@ Line 77: / Line 48: @@
 #define INCL_WIN
-#include
+#include <os2.h>
 int main(void)
@@ Line 100: / Line 71: @@
 } /* main */
 </pre>
-=== See Also ===
-[[OS2 API:PMI:PrfOpenProfile|PrfOpenProfile]]
-[[Category:The OS/2 API Project]]
+[[Category:Prf]]