docs(audit): apply per-cluster judgment fixes across living docs
Resolve audit findings: correct WorkerEnvelope proto/route/metric/session facts; rewrite auth (ZB.MOM.WW.Auth migration), dashboard (ZB.MOM.WW.Theme), and StyleGuide (foreign-project copy-paste); document alarm subsystem, Ldap options, and gateway alarm broker; fix client CLI flags and package paths.
This commit is contained in:
@@ -109,6 +109,30 @@ default:
|
||||
|
||||
The MXAccess engine returns values whose semantic type only fully resolves after consulting the engine's own attribute metadata. Clients that round-trip these values through the gateway (replay, parity fixtures, diagnostics) need the original `VT_*` tag, the engine-declared `MxDataType`, and any conversion diagnostic; otherwise edge cases such as decimal-to-double rounding, ulong overflow, or an unknown SAFEARRAY element type become invisible bugs. Storing both the typed projection and the raw fields in the same `MxValue`/`MxArray` lets cross-language clients recover the original observation byte-for-byte where possible and detect lossy cases where it is not.
|
||||
|
||||
### Inverse projection for COM writes
|
||||
|
||||
The conversions above run on the read path, turning COM values into `MxValue`.
|
||||
The write path runs the same `VariantConverter` in reverse: `ConvertToComValue`
|
||||
takes an `MxValue` from a `Write` command and returns a CLR object that the COM
|
||||
marshaler boxes into the matching VARIANT, so it is the inverse of `Convert`.
|
||||
|
||||
- A null `MxValue` argument throws; an `MxValue` whose `IsNull` flag is set
|
||||
returns `null` (the MXAccess null), keeping the read/write null semantics
|
||||
symmetric.
|
||||
- Each `KindCase` maps to its CLR scalar (`bool`, `int`, `long`, `float`,
|
||||
`double`, `string`). A `TimestampValue` becomes a `DateTime`, which the
|
||||
marshaler renders as `VT_DATE` — the form MXAccess accepts for the
|
||||
timestamped-write argument.
|
||||
- An array kind delegates to `ConvertToComArray`, which projects each
|
||||
`MxArray.ValuesCase` to a typed CLR array (for example `int[]`, `string[]`, or
|
||||
a `DateTime[]` for timestamp arrays) so the marshaler produces the
|
||||
corresponding SAFEARRAY.
|
||||
- `RawValue` payloads are intentionally rejected on both the scalar and array
|
||||
paths. Raw bytes are preserved on the read path for diagnostics, but there is
|
||||
no safe way to reconstruct the original VARIANT from them, so a write that
|
||||
carries a raw value throws rather than guessing. An `MxValue` with no value
|
||||
kind set throws for the same reason — there is nothing to write.
|
||||
|
||||
## HResultConverter and HResultConversion
|
||||
|
||||
`HResultConverter.Convert` wraps any `Exception` thrown across the COM boundary. It prefers `COMException.ErrorCode` over `Exception.HResult` because the runtime sometimes overwrites `Exception.HResult` while marshalling, and the `ErrorCode` field is the value the COM call actually returned.
|
||||
@@ -223,7 +247,7 @@ public string PreserveCompletionOnlyStatusBytes(byte[] statusBytes)
|
||||
|
||||
`MxStatusDetailText` is an internal lookup that maps known `MXSTATUS_PROXY.detail` codes to short human-readable strings (for example `28 = "Index out of range"`, `42 = "Unable to convert string"`, `8017 = "Object must be offscan to modify attributes that have an MxSecurityConfigure security classification"`). `MxStatusProxyConverter.Convert` calls `Lookup` and writes the result to `DiagnosticText`. Unknown codes return `string.Empty`, leaving the numeric `Detail` field as the authoritative identifier.
|
||||
|
||||
The mapping covers the engine-error range documented for MXAccess (16-50, 56-61, 541-542, 8017). Adding entries here is the supported way to enrich wire-level diagnostics without changing the proto schema.
|
||||
The mapping covers selected detail codes in the MXAccess engine-error ranges (16-50, 56-61, 541-542, 8017). The ranges are not contiguous: codes that the runtime does not assign a distinct meaning are omitted (for example 35, 45, and 46 in the 16-50 range and 58-59 in the 56-61 range), so only codes with a known text appear. Adding entries here is the supported way to enrich wire-level diagnostics without changing the proto schema.
|
||||
|
||||
## MxStatusConversionException
|
||||
|
||||
|
||||
Reference in New Issue
Block a user