Description
Reports information about the directory of a PowerBuilder library, including the list of objects in the directory.
Syntax
INT PBORCA_LibraryDirectory ( HPBORCA hORCASession, LPTSTR lpszLibName, LPTSTR lpszLibComments, INT iCmntsBuffLen, PBORCA_LISTPROC pListProc, LPVOID pUserData );
|
Argument |
Description |
|---|---|
|
hORCASession |
Handle to previously established ORCA session. |
|
lpszLibName |
Pointer to a string whose value is the file name of the library for which you want directory information. |
|
lpszLibComments |
Pointer to a buffer in which ORCA will put comments stored with the library. |
|
iCmntsBuffLen |
Length of the buffer (specified in TCHARs) pointed to by lpszLibComments. The recommended length is PBORCA_MAXCOMMENTS + 1. |
|
pListProc |
Pointer to the PBORCA_LibraryDirectory callback function. The callback function is called for each entry in the library. The information ORCA passes to the callback function is entry name, comments, size of entry, and modification time, stored in a structure of type PBORCA_DIRENTRY. |
|
pUserData |
Pointer to user data to be passed to the PBORCA_LibraryDirectory callback function. The user data typically includes the buffer or a pointer to the buffer in which the callback function formats the directory information as well as information about the size of the buffer. |
Return value
INT. Typical return codes are:
|
Return code |
Description |
|---|---|
|
0 PBORCA_OK |
Operation successful |
|
-1 PBORCA_INVALIDPARMS |
Invalid parameter list |
|
-4 PBORCA_BADLIBRARY |
Bad library name |
|
-7 PBORCA_LIBIOERROR |
Library I/O error |
Usage
You do not need to set the library list or current application before calling this function.
Comments for the library
PBORCA_LibraryDirectory puts the library comments in the string pointed to by lpszLibComments. The callback function can store comments for individual objects in the UserData buffer.
Information about library entries
The information you get back about the individual entries in the library depends on the processing you provide in the callback function. ORCA passes information to the callback function about a library entry in the structure PBORCA_DIRENTRY. The callback function can examine that structure and store any information it wants in the buffer pointed to by pUserData.
When you call PBORCA_LibraryDirectory, you do not know how many entries there are in the library. There are two approaches you can take:
-
Allocate a reasonably sized block of memory and reallocate the buffer if it overflows (illustrated in About ORCA callback functions).
-
Let lpUserDataBuffer point to the head of a linked list. For each PBORCA_DIRENTRY returned, dynamically allocate a new list entry to capture the required information (illustrated in the example that follows).
Examples
This example defines a linked list header:
typedef struct libinfo_head
{
TCHAR szLibName[PBORCA_SCC_PATH_LEN];
TCHAR szComments[PBORCA_MAXCOMMENT+1];
INT iNumEntries;
PLIBINFO_ENTRY pEntryAnchor;
PLIBINFO_ENTRY pLast;
} LIBINFO_HEAD, FAR *PLIBINFO_HEAD;Each invocation of the DirectoryProc callback function allocates a new linked list entry, defined as follows:
typedef struct libinfo_entry
{
TCHAR szEntryName[41];
LONG lEntrySize;
LONG lObjectSize;
LONG lSourceSize;
PBORCA_TYPE otEntryType;
libinfo_entry * pNext;
} LIBINFO_ENTRY, FAR *PLIBINFO_ENTRY;
PBORCA_LISTPROC fpDirectoryProc;
PLIBINFO_HEAD pHead;
fpDirectoryProc = (PBORCA_LISTPROC) DirectoryProc;
pHead = new LIBINFO_HEAD;
_tcscpy(pHead->szLibName, _TEXT("c:\\myapp\test.pbl");
memset(pHead->szComments, 0x00,
sizeof(pHead->szComments));
pHead->iNumEntries = 0;
pHead->pEntryAnchor = NULL;
pHead->pLast = NULL;
lpORCA_Info->lReturnCode = PBORCA_LibraryDirectory(
lpORCA_Info->hORCASession,
pHead->szLibName,
pHead->szComments,
(PBORCA_MAXCOMMENT+1), // specify length in TCHARs
fpDirectoryProc,
pHead);
// See PBORCA_LibraryEntryInformation example
if (lpORCA_Info->lReturnCode == PBORCA_OK)
GetEntryInfo(pHead);
CleanUp(pHead);
// CleanUp - Release allocated memory
INT CleanUp(PLIBINFO_HEAD pHead)
{
INT iErrCode = PBORCA_OK;
PLIBINFO_ENTRY pCurrEntry;
PLIBINFO_ENTRY pNext;
INT idx;
for (idx = 0, pCurrEntry = pHead->pEntryAnchor;
(idx < pHead->iNumEntries) && pCurrEntry; idx++)
{
pNext = pCurrEntry->pNext;
delete pCurrEntry;
if (pNext)
pCurrEntry = pNext;
else pCurrEntry = NULL;
}
delete pHead;
return iErrCode;
}
// Callback procedure used by PBORCA_LibraryDirectory
void __stdcall DirectoryProc(PBORCA_DIRENTRY
*pDirEntry, LPVOID lpUserData)
{
PLIBINFO_HEAD pHead;
PLIBINFO_ENTRY pNewEntry;
PLIBINFO_ENTRY pTemp;
pHead = (PLIBINFO_HEAD) lpUserData;
pNewEntry = (PLIBINFO_ENTRY) new LIBINFO_ENTRY;
memset(pNewEntry, 0x00, sizeof(LIBINFO_ENTRY));
if (pHead->iNumEntries == 0)
{
pHead->pEntryAnchor = pNewEntry;
pHead->pLast = pNewEntry;
}
else
{
pTemp = pHead->pLast;
pTemp->pNext = pNewEntry;
pHead->pLast = pNewEntry;
}
pHead->iNumEntries++;
_tcscpy(pNewEntry->szEntryName,
pDirEntry->lpszEntryName);
pNewEntry->lEntrySize = pDirEntry->lEntrySize;
pNewEntry->otEntryType = pDirEntry->otEntryType;In these examples, session information is saved in the data structure ORCA_Info, shown in About the examples.
See also
