microsoft / microsoft/win32metadata

Create enums for stronger typing of ESENT API

Open
#1,737 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
1.5k
Forks
149
Avg merge
5d 16h
Merged PRs (30d)
4

Description

The ESE API (also known as JET Blue) can use some finer tuning to preserve some of the metadata.

The relevant header file is at `generation/WinSDK/RecompiledIdlHeaders/um/esent.h`.
The API as a whole is documented at: https://learn.microsoft.com/en-us/windows/win32/extensible-storage-engine/extensible-storage-engine-reference

- `JET_ERR`
- This return type is similar to an `HRESULT` in that negative values are failures, and positive are warnings.
Examples are `JET_errSuccess`, `JET_errInvalidParameter`, `JET_wrnBufferTruncated`.
https://github.com/search?q=repo%3Amicrosoft%2Fwin32metadata%20JET_ERR&type=code
```C++
typedef _Return_type_success_( return >= 0 ) long JET_ERR;
```
- `JET_param`
- A large number of "Parameters", used mostly with `JetGetSystemParameter` / `JetSetSystemParameter`.
- `JET_grbit`
- The bitflags taken by various APIs. There are dozens of different APIs that take different sets of values.
- The C# API attempted to separate them out. https://github.com/search?q=repo%3Amicrosoft%2FManagedEsent+path%3A**%2F*grbits*.cs&type=code
- Although the C# API did something that seemed like a good idea at the time, but maybe wasn't in hindsight: Values that were added to different versions of Windows were split up in to different classes (e.g. `VistaGrbits.cs`). This moved the cross-version compatibility question to a compile-time error/decision, but over the years, it has also caused confusion.
- It would be nice to create separate enums for each API, but that might be out of scope of this request.
- `Nil` values
- These following `Nil` values should ideally also be expressed symbolically:
```C++
#define JET_instanceNil (~(JET_INSTANCE)0)
#define JET_sesidNil (~(JET_SESID)0)
#define JET_tableidNil (~(JET_TABLEID)0)
#define JET_bitNil ((JET_GRBIT)0)
```

Contributor guide

Open the contributing guide

Research direction

Start with generation/WinSDK/RecompiledIdlHeaders/um/esent.h and compare its JET_ERR, JET_param, JET_grbit, and Nil definitions with the ESE API reference. Review the linked ManagedEsent grbit examples for possible enum organization. Done means the requested metadata is represented symbolically while preserving the documented values and compatibility considerations.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
operating-systems, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.