Share via

CeOpenDatabaseInSession (EDB)

  • Article

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function opens an existing database in a mounted volume The volume must be mounted with the CeMountDBVolEx (EDB) function.

Syntax

HANDLE CeOpenDatabaseInSession(
  HANDLE hSession,
  PCEGUID pGuid,
  PCEOID poid,
  LPWSTR lpwszName,
  SORTORDERSPECEX* pSort,
  DWORD dwFlags,
  CENOTIFYREQUEST* pRequest
);

Parameters

  • hSession
    [in] Handle to the session. This handle must be returned from either the CeCreateSession (EDB) or the CeGetDatabaseSession (EDB) function. This parameter can be set to NULL, in which case all changes made to the opened database are atomic. This means that each change is committed to the database and then written to file once a flush occurs. If this parameter is not set to NULL, 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] Pointer to the CEGUID of a mounted database volume. If this parameter is a valid GUID, the volume specified is used. If this parameter points to a CEGUID created with CREATE_INVALIDEDBGUID, the poid parameter is ignored, and all mounted database volumes are searched for the first database whose name matches the lpwszName parameter.
  • poid
    [in, out] Pointer to the OID of the database to be opened. To open a database by name, set this parameter to zero, set lpwszName to the database name, and set pGuid ** to the database volume.
  • lpwszName
    [in] 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 zero. When a database is opened by name, poid contain the OID of the opened database on return. If the value pointed to by poid is nonzero, lpwszName is ignored.
  • pSort
    [in] 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 set to NULL, 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, the property IDs and the flags must match the values used for one of the database sort orders.

  • dwFlags
    [in] The following are possible values:

    • CEDB_AUTOINCREMENT: The current seek position is automatically incremented with each call to the CeReadRecordPropsEx (EDB) function.
    • Zero: The current position is not incremented with each call to the CeReadRecordPropsEx function.
  • pRequest
    [in] Pointer to a CENOTIFYREQUEST structure that requests that notifications be sent to the specified window. This parameter can be set to NULL if an application does not need to receive notifications.

Return Value

A handle to the open database indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError. The following table shows possible values.

Return Value Description

ERROR_FILE_NOT_FOUND

The database specified by either poid or lpwszName does not exist.

ERROR_INVALID_HANDLE

The hSession parameter is equal to INVALID_HANDLE_VALUE.

ERROR_INVALID_PARAMETER

One or more parameters are invalid.

ERROR_NOT_ENOUGH_MEMORY

There is not enough memory to allocate the database handle.

ERROR_NOT_FOUND

The volume specified by pGuid does not exist.

Remarks

The ERROR_INVALID_PARAMETER can be returned in the following situations:

  • The hSession parameter is not set to NULL, and the volume GUID of session does not match the GUID specified by pGuid.
  • The ** pGuid parameter is set to NULL.
  • The ** pGuid parameter contains a GUID created with the CREATE_INVALIDEDBGUID function, and lpwszName is set to NULL.
  • The ** pGuid parameter is not an invalid GUID, and poid is set to NULL.
  • The ** pGuid parameter is not an invalid GUID, *poid is equal to zero, and lpwszName is set to NULL.
  • The pSort parameter is not set to NULL and an existing sort order on the database cannot be found that matches the property IDs and flags specified in pSort.
  • The dwFlags parameter does not contain a valid flag.
  • The pRequest parameter is not set to NULL. The following situations can cause this error:
    • The dwSize member of CENOTIFYREQUEST returned by pRequest is not equal to the size of CENOTIFYREQUEST.
    • The hwnd member of CENOTIFYREQUEST returned by pRequest is not a valid window handle.

The handle returned from this function is a free-threaded handle that can be used on multiple threads at the same time. It must be closed by calling the CloseHandle function.

The following are 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 record. If CEDB_AUTOINCREMENT is not specified, the seek pointer is not positioned on a record, and the user must call the CeSeekDatabaseEx function. This differs from CEDB, in which the seek pointer is always positioned on the first record, regardless of whether CEDB_AUTOINCREMENT is specified.
  • EDB does not support a system volume, and so calling this function with pGuid set to CREATE_SYSTEMGUID fails and returns ERROR_NOT_FOUND.
  • If pSort is set to NULL, EDB does not use a sort order, but CEDB chooses a default sort order.
  • EDB supports multiple sort orders on the same property. Two sort orders on the same property are differentiated by their flags. Therefore, sort orders cannot be uniquely identified by property IDs alone, and CeOpenDatabaseInSession fails if the sort order does not contain the flags that were used when the sort order was created.
  • CREATE_INVALIDEDBGUID is used to enumerate CEDB and EDB volumes.

Requirements

Header windbase.h
Library coredll.lib
Windows Embedded CE Windows CE 5.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also

Reference

EDB Functions
CeMountDBVolEx (EDB)
CeCreateSession (EDB)
CeGetDatabaseSession (EDB)
CeSeekDatabaseEx (EDB)
CeReadRecordPropsEx (EDB)