CeOpenDatabaseInSession (EDB) (Windows CE 5.0)
This function is used to open an existing database that is in a mounted volume The volume must be mounted by using the CeMountDBVol (EDB) function.
This function does not work with CEDB databases. For more information about CEDB, see CEDB Reference.
HANDLE CeOpenDatabaseInSession(HANDLEhSession,PCEGUIDpGuid,PCEOIDpoid,LPWSTRlpwszName,SORTORDERSPECEX*pSort,DWORDdwFlags,CENOTIFYREQUEST*pRequest);
Parameters
- hSession
[in] A handle to the session. This handle must be returned from either the CeCreateSession (EDB) or the CeGetDatabaseSession (EDB) function. This parameter can be NULL, in which case all changes made to the opened database are atomic (also called auto-commit); that is, each change is committed to the database and then written to file once a flush occurs. If this parameter is not NULL, then the value specified in the pGuid parameter must match the CEGUID of the volume from which this session handle was created; otherwise this function fails. - pGuid
[in] A pointer to the CEGUID of a mounted database volume. If pGuid is a valid GUID, then the volume specified by pGuid is used. If pGuid points to a CEGUID created with CREATE_INVALIDEDBGUID, then poid is ignored and all mounted database volumes are searched for the first database whose name matches lpwszName. - poid
[in/out] A pointer to the OID of the database to be opened. To open a database by name, set the value pointed to by poid to 0, set lpwszName to the database name, and set pGuid to the database volume. - lpwszName
[in] A pointer to the null-terminated string that contains the name of the database to be opened. This is used along with pGuid to specify the database if the value pointed to by poid is 0. When a database is opened by name, then poid will contain (on return) the OID of the opened database. If the value pointed to by poid is nonzero, lpwszName is ignored. - pSort
[in] A pointer to the active sort order for the database. All subsequent calls to the CeSeekDatabaseEx (EDB) function assume this sort order. If this parameter is NULL, then no sort order is chosen. If the sort pointer does not point to one of the sort structures used in the creation of the database, then the property IDs**and the flags must match the values used for one of the database sort orders. - dwFlags
[in] An action flag that is one of the following values:CEDB_AUTOINCREMENT
With this flag set, the current seek position is automatically incremented with each call to the CeReadRecordPropsEx (EDB) function.
0 (zero)
With this value, the current position is not incremented with each call to the CeReadRecordPropsEx function.
- pRequest
[in] A pointer to a CENOTIFYREQUEST structure that requests that notifications be sent to an identified window. This parameter can be NULL if an application does not need to receive notifications.
Return Values
A handle to the open database indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError. The following table lists possible values returned by GetLastError:
| Return Value | Description |
|---|---|
| ERROR_INVALID_PARAMETER | Indicates that one or more parameters are invalid. See "Remarks" later in this topic for more information. |
| ERROR_INVALID_HANDLE | Indicates that hSession is equal to INVALID_HANDLE_VALUE. |
| ERROR_NOT_FOUND | Indicates that the volume specified by pGuid does not exist. |
| ERROR_FILE_NOT_FOUND | Indicates that the database specified by either poid or lpwszName cannot be found or does not exist. |
| ERROR_NOT_ENOUGH_MEMORY | Indicates that no memory was available to allocate the database handle. |
Remarks
The ERROR_INVALID_PARAMETER may be returned in the following situations:
- hSession is not NULL, and the volume GUID that the session was created with does not match the GUID specified by the pGuid parameter.
- pGuid is NULL.
- pGuid contains a GUID created with the CREATE_INVALIDEDBGUID function and lpwszName is NULL.
- pGuid is not an invalid GUID and poid is NULL.
- pGuid is not an invalid GUID, *poid is equal to 0, and lpwszName is NULL.
- pSort is not null and an existing sort order on the database cannot be found that matches the same set of property IDs and flags specified in pSort.
- dwFlags does not contain a valid flag.
- pRequest is not NULL. The following situations can cause this error:
- *pRequest->*dwSize is not equal to the size of CENOTIFYREQUEST.
- *pRequest->*hwnd is not a valid window handle.
The handle returned from this function is a free-threaded handle and can be used on multiple threads at the same time. It must be closed by calling the CloseHandle function.
The following list highlights the differences between this function and the CEDB equivalent function:
- In EDB, if CEDB_AUTOINCREMENT is specified when the database is opened, the seek pointer is positioned on the first row. If CEDB_AUTOINCREMENT is not specified, then the seek pointer is not positioned on a row and the user must call the CeSeekDatabaseEx function. This differs from CEDB, where the seek pointer is always positioned on the first row regardless of whether CEDB_AUTOINCREMENT is specified.
- EDB does not support a system volume and so calling this with pGuid set to CREATE_SYSTEMGUID fails, returning ERROR_NOT_FOUND.
- If pSort is NULL, EDB does not use a sort order, but CEDB chooses a default sort order.
- EDB allows multiple sort orders on the same property. Two sort orders on the same property are differentiated by their flags. As a consequence, sort orders cannot be uniquely identified by property IDs alone, and the CeOpenDatabaseInSession (EDB) function fails if the sort order does not contain the same flags that were used when the sort order was created.
- CREATE_INVALIDEDBGUID is used to enumerate CEDB and EDB volumes.
Requirements
OS Versions: Windows CE 5.0 and later.
Header: Windbase.h.
Link Library: Coredll.lib.
See Also
CeMountDBVol (EDB) | CeCreateSession (EDB) | CeGetDatabaseSession (EDB) | CeSeekDatabaseEx (EDB) | CeReadRecordPropsEx (EDB)
Send Feedback on this topic to the authors