Nintendo Switch Brew

NS services: Difference between revisions

← Older edit
 
(62 intermediate revisions by the same user not shown)
Line 406: Line 406:
These are "nn::ns::detail::IServiceGetterInterface".
These are "nn::ns::detail::IServiceGetterInterface".


These commands check a state field for a command-specific bit and returns an error if not set, this is likely a permissions check for service+command.
These commands check a state field for a command-specific bit and returns an error if not set, this is a permissions check for service+command.


[11.0.0+] ns:ro was added.
[11.0.0+] ns:ro was added.
Line 414: Line 414:
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
! Cmd || Name
! Cmd || Name || Permission bit
|-
|-
| 7988 || [6.0.0+] [[#IDynamicRightsInterface|GetDynamicRightsInterface]]
| 7988 || [6.0.0+] [[#IDynamicRightsInterface|GetDynamicRightsInterface]] || 10
|-
|-
| 7989 || [5.1.0+] [[#IReadOnlyApplicationControlDataInterface|GetReadOnlyApplicationControlDataInterface]]
| 7989 || [5.1.0+] [[#IReadOnlyApplicationControlDataInterface|GetReadOnlyApplicationControlDataInterface]] || 9
|-
|-
| 7991 || [5.0.0+] [[#IReadOnlyApplicationRecordInterface|GetReadOnlyApplicationRecordInterface]]
| 7991 || [5.0.0+] [[#IReadOnlyApplicationRecordInterface|GetReadOnlyApplicationRecordInterface]] || 8
|-
|-
| 7992 || [4.0.0+] [[#IECommerceInterface|GetECommerceInterface]]
| 7992 || [4.0.0+] [[#IECommerceInterface|GetECommerceInterface]] || 7
|-
|-
| 7993 || [4.0.0+] [[#IApplicationVersionInterface|GetApplicationVersionInterface]]
| 7993 || [4.0.0+] [[#IApplicationVersionInterface|GetApplicationVersionInterface]] || 6
|-
|-
| 7994 || [[#IFactoryResetInterface|GetFactoryResetInterface]]
| 7994 || [[#IFactoryResetInterface|GetFactoryResetInterface]] || 5
|-
|-
| 7995 || [[#IAccountProxyInterface|GetAccountProxyInterface]]
| 7995 || [[#IAccountProxyInterface|GetAccountProxyInterface]] || 4
|-
|-
| 7996 || [[#IApplicationManagerInterface|GetApplicationManagerInterface]]
| 7996 || [[#IApplicationManagerInterface|GetApplicationManagerInterface]] || 3
|-
|-
| 7997 || [[#IDownloadTaskInterface|GetDownloadTaskInterface]]
| 7997 || [[#IDownloadTaskInterface|GetDownloadTaskInterface]] || 1
|-
|-
| 7998 || [[#IContentManagementInterface|GetContentManagementInterface]]
| 7998 || [[#IContentManagementInterface|GetContentManagementInterface]] || 0
|-
|-
| 7999 || [[#IDocumentInterface|GetDocumentInterface]]
| 7999 || [[#IDocumentInterface|GetDocumentInterface]] || 2
|}
 
Permissions state field with each service:
 
{| class="wikitable" border="1"
|-
! Service || Permissions
|-
| ns:web || 0x304
|-
| ns:ec || 0x83
|-
| ns:sweb || 0x387
|-
| ns:rid || 0x10
|-
| ns:rt || 0x20
|-
| ns:ro || 0x301
|-
| ns:am2 || 0x7FF
|}
|}


Line 649: Line 670:
|-
|-
| 307 || TerminateOverlayApplet
| 307 || TerminateOverlayApplet
|-
| 308 || [S2]
|-
| 309 || [S2]
|-
|-
| 400 || [[#GetApplicationControlData]]
| 400 || [[#GetApplicationControlData]]
Line 667: Line 692:
|-
|-
| 408 || [8.0.0+] [[#ListApplicationIcon]]
| 408 || [8.0.0+] [[#ListApplicationIcon]]
|-
| 409 || [S2]
|-
| 410 || [S2]
|-
|-
| 411 || [19.0.0+]
| 411 || [19.0.0+]
Line 817: Line 846:
|-
|-
| 923 || [20.0.0+]
| 923 || [20.0.0+]
|-
| 924 || [S2]
|-
| 925 || [S2]
|-
| 926 || [S2]
|-
| 927 || [S2]
|-
|-
| 928 || [20.0.0+]
| 928 || [20.0.0+]
Line 825: Line 862:
|-
|-
| 931 || [20.0.0+]
| 931 || [20.0.0+]
|-
| 933 || [20.1.0+]
|-
|-
| 1000 || [[#RequestVerifyApplicationDeprecated]]
| 1000 || [[#RequestVerifyApplicationDeprecated]]
Line 999: Line 1,038:
|-
|-
| 2182 || [6.0.0+] SetActiveRightsContextUsingStateToRightsEnvironment
| 2182 || [6.0.0+] SetActiveRightsContextUsingStateToRightsEnvironment
|-
| 2183 || [20.1.0+]
|-
|-
| 2190 || [6.0.0+] [[#GetRightsEnvironmentHandleForApplication]]
| 2190 || [6.0.0+] [[#GetRightsEnvironmentHandleForApplication]]
Line 1,128: Line 1,169:
| 3050 || [14.0.0+] ListAssignELicenseTaskResult
| 3050 || [14.0.0+] ListAssignELicenseTaskResult
|-
|-
| 3100 || [17.0.0+] GetSafeSystemVersionCheckInfo
| 3100 || [17.0.0+] [[#GetSafeSystemVersionCheckInfo|GetSafeSystemVersionCheckInfo]]
|-
|-
| 3101 || [17.0.0+] RequestUpdateSafeSystemVersionCheckInfo
| 3101 || [17.0.0+] [[#RequestUpdateSafeSystemVersionCheckInfo|RequestUpdateSafeSystemVersionCheckInfo]]
|-
|-
| 3102 || [17.0.0+] ResetSafeSystemVersionCheckInfo
| 3102 || [17.0.0+] [[#ResetSafeSystemVersionCheckInfo|ResetSafeSystemVersionCheckInfo]]
|-
|-
| 3104 || [18.0.0+] GetApplicationNintendoLogo
| 3104 || [18.0.0+] GetApplicationNintendoLogo
|-
|-
| 3105 || [18.0.0+] GetApplicationStartupMovie
| 3105 || [18.0.0+] GetApplicationStartupMovie
|-
| 3150 || [S2]
|-
|-
| 4000 || [20.0.0+]
| 4000 || [20.0.0+]
Line 1,389: Line 1,432:
==== GetRequestServerStopper ====
==== GetRequestServerStopper ====
No input, returns an output [[#IRequestServerStopper]].
No input, returns an output [[#IRequestServerStopper]].
This increfs a state ref-count, with decref being handled when the object is closed. This ref-count is checked by [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]] and related cmds.


==== CancelApplicationApplyDelta ====
==== CancelApplicationApplyDelta ====
Line 1,478: Line 1,523:
No input, returns an output u64.
No input, returns an output u64.


A state flag must be non-zero, otherwise an error is thrown. When a state field is value 1, a hard-coded ProgramId for MaintenanceMenu is used. Otherwise, the ProgramId is loaded from [[System_Settings|system-setting]] <code>ns.applet!system_applet_id</code>.
A state flag must be non-zero, otherwise an error is thrown. When a state field is value 1, a hard-coded ProgramId for MaintenanceMenu is used. Otherwise, the ProgramId is loaded from [[System_Settings|system-setting]] <code>ns.applet!system_applet_id</code> ([20.0.0+] <code>ns.applet!system_applet_id_gen2</code>).


The SystemApplet is launched with StorageId=BuiltInSystem via [[Process_Manager_services|pmshell]] LaunchProgram ([10.0.0+] [[PGL_services#LaunchProgram|pgl]] with pgl_launch_flags=0). [[Process_Manager_services#LaunchFlags|LaunchFlags]] value 0x9 is used here. The output u64 from here is written to the output for this cmd, on success.
The SystemApplet is launched with StorageId=BuiltInSystem via [[Process_Manager_services|pmshell]] LaunchProgram ([10.0.0+] [[PGL_services#LaunchProgram|pgl]] with pgl_launch_flags=0). [[Process_Manager_services#LaunchFlags|LaunchFlags]] value 0x9 is used here. The output u64 from here is written to the output for this cmd, on success.
Line 1,658: Line 1,703:
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], and returns an output s32.
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], and returns an output s32.


This determines the latest version from the input [[#ApplicationDeliveryInfo]] array, using value 0 if the array is empty. If this value is less than a state field, the state field value is used instead. Then this selects a [[#SystemDeliveryInfo]] with the latest version from the input array, where the minimum version is the previously mentioned value. The version must also be also be at least the version value from the type-0x15 [[#SystemDeliveryInfo]] buffer. This also does various validation, etc. The output s32 is an index in that array for the selected entry, -1 if none found.
This determines the latest version (RequiredSystemVersion) from the input [[#ApplicationDeliveryInfo]] array (ApplicationDeliveryProtocolVersion and the HMAC are also validated), using value 0 if the array is empty.
 
* [20.0.0+] The following code block now only runs when the SystemDeliveryInfoPlatform from the type-0x15 [[#SystemDeliveryInfo]] buffer matches the [[System_Settings|sys-setting]].
** It then loops through the [[#ApplicationDeliveryInfo]] array again:
** This uses functionality which essentially uses [[Shared_Database_services|pl:s]] GetFunctionBlackListSystemVersionToAuthorize with the [[#ApplicationDeliveryInfo]] ApplicationId and ApplicationFunctionAuthorizationId=0x5 then parses the output, using cached data if available. The error is returned on failure.
** tmp_version = out_u8 == 0 ? 0 : out_u32 + 0x10000;
** Then the current latest-version value is updated with tmp_version, if tmp_version is higher.
 
If this version value is less than a state field, the state field value is used instead (state field originates from [[System_Settings|system-setting]] <code>contents_delivery!required_system_version_to_deliver_application</code>).
 
Then this selects the [[#SystemDeliveryInfo]] with the latest version from the input array. The output s32 is an index in that array for the selected entry, -1 if none found.
 
During the above loop it first calls the [[#SystemDeliveryInfo]] validation func, returning the Result on failure. Then it runs additional validation, with the [[#SystemDeliveryInfo]] entry being ignored on failure:
* The above latest-version value must be at least the version value from the type-0x15 [[#SystemDeliveryInfo]] buffer and the [[#SystemDeliveryInfo]] array entry.
* When HasExFat is set in the type-0x15 [[#SystemDeliveryInfo]] buffer, it must be set in the [[#SystemDeliveryInfo]] array entry.
* FirmwareVariationId in the type-0x15 [[#SystemDeliveryInfo]] buffer must not be 0xFF.
* UpdatableFirmwareGroupId in the [[#SystemDeliveryInfo]] array entry must not be 0xFF. The value must be within bounds of the settings array ([[System_Settings|sys-settings]] <code>contents_delivery!updatable_firmware_group_string</code>).
* PlatformRegion in the [[#SystemDeliveryInfo]] array entry and the type-0x15 [[#SystemDeliveryInfo]] buffer must match.
* Lastly when the following is true, this indicates success: (settings_array[UpdatableFirmwareGroupId] >> {above FirmwareVariationId}) & 1.


==== VerifyDeliveryProtocolVersion ====
==== VerifyDeliveryProtocolVersion ====
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], no output.
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], no output.


This validates the [[#SystemDeliveryInfo]] HMAC and the protocol-version fields. Then the meta version is compared with a state field, an error is returned on match otherwise 0 is returned.
This validates the [[#SystemDeliveryInfo]] HMAC and the protocol-version fields. Then an error is returned when SystemUpdateVersion is less than a state field, otherwise 0 is returned (state field originates from [[System_Settings|system-setting]] <code>contents_delivery!required_system_version_to_deliver_application</code>).


==== GetApplicationDeliveryInfo ====
==== GetApplicationDeliveryInfo ====
Takes a type-0x6 output buffer containing an array of [[#ApplicationDeliveryInfo]], an input u32 bitmask <code>nn::ns::ApplicationDeliveryAttributeTag</code>, an [[NCM_services#ApplicationId|ApplicationId]], and returns an output s32 total_out.
Takes a type-0x6 output buffer containing an array of [[#ApplicationDeliveryInfo|ApplicationDeliveryInfo]], an input u32 bitmask <code>nn::ns::ApplicationDeliveryAttributeTag</code>, an [[NCM_services#ApplicationId|ApplicationId]], and returns an output s32 total_out.


An error is thrown if any bit is set in ApplicationDeliveryAttributeTag besides bit1. The output array-count must be at least 1: only 1 entry will be written to this array (hence on success total_out will also only be 1 on success).
[11.0.0+] An error is thrown if LocalContentShare is not [[#IsLocalContentShareEnabled|enabled]].
 
An error is thrown if any bit is set in ApplicationDeliveryAttributeTag besides bit1, this must also be <=0x3. The output array-count must be at least 1: only 1 entry will be written to this array (hence on success total_out will also only be 1 on success).
 
[7.0.0+] An error is thrown if the state ref-count for [[#GetRequestServerStopper|RequestServerStopper]] is zero. [7.0.0-7.0.1] The func which checks this would also return success when a field prior to the previously mentioned field is 0 (checked before the ref-count).
 
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
 
HasApplicationRecord is called with the input [[NCM_services#ApplicationId|ApplicationId]], an error is returned if the record isn't found.
 
[[#ApplicationDeliveryInfo|RequiredApplicationVersion]] is initially set to the output version from [[Shared_Database_services|avm]] GetLaunchRequiredVersion. Later when ContentMetaType == Application etc, it calls a func. This func uses [[NCM_services|ncm]] IContentMetaDatabase GetRequiredApplicationVersion. If the output version is higher than the [[#ApplicationDeliveryInfo|RequiredApplicationVersion]] field then the output version is written here. Immediately aferwards, it also checks whether the bit for Compacted is set from [[NCM_services|ncm]] IContentMetaDatabase GetAttributes, clearing [[#ApplicationDeliveryInfo|ApplicationVersion]] if the attribute is set.
 
[20.0.0+] [[#ApplicationDeliveryInfo|ApplicationDeliveryInfo]] ContentMetaPlatform and ProperProgramExists are now set using data from [[NCM_services|ncm]].
 
[20.0.0+] [[Shared_Database_services|pl:s]] GetFunctionBlackListSystemVersionToAuthorize with ApplicationFunctionAuthorizationId=0x5 is now used, the output version is written to [[#ApplicationDeliveryInfo|RequiredSystemVersion]] when it's higher than the value previously written here.
 
[20.0.0+] [[Shared_Database_services|pl:s]] GetRequiredApplicationVersion with ApplicationFunctionAuthorizationId=0x5 is now used, the output version is written to [[#ApplicationDeliveryInfo|RequiredApplicationVersion]] when it's higher than the value previously written here.


==== HasAllContentsToDeliver ====
==== HasAllContentsToDeliver ====
Takes a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], returns an output u8 bool.
Takes a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], returns an output u8 bool.


The array-count must match 1. After validating the [[#ApplicationDeliveryInfo]], the output bool is set to u32 [[#ApplicationDeliveryInfo]]+0x1C & 0x10000002 != 0x2, then this returns 0.
The array-count must match 1.
 
This uses the same LocalContentShare check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
 
After validating the [[#ApplicationDeliveryInfo]], the output bool is set to [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] & 0x10000002 != 0x2, then this returns 0.


==== CompareApplicationDeliveryInfo ====
==== CompareApplicationDeliveryInfo ====
Takes two type-0x5 input buffers containing an array of [[#ApplicationDeliveryInfo]], returns an output s32.
Takes two type-0x5 input buffers containing an array of [[#ApplicationDeliveryInfo]], returns an output s32.
This uses the same LocalContentShare check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].


The array-count for both buffers must be 1, otherwise an error is returned.
The array-count for both buffers must be 1, otherwise an error is returned.
Line 1,685: Line 1,770:
Takes two type-0x5 input buffers containing an array of [[#ApplicationDeliveryInfo]], returns an output u8 bool.
Takes two type-0x5 input buffers containing an array of [[#ApplicationDeliveryInfo]], returns an output u8 bool.


The array-count for the second buffer must be 1 and the array-count for the first buffer must be <=1, otherwise an error is returned. If the array-count for the first buffer is 0, this will return 0 with the output bool set to 0.
The array-count for the second buffer must be 1, otherwise an error is returned.
 
This uses the same LocalContentShare check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
 
The second [[#ApplicationDeliveryInfo]] buffer is validated. An error is thrown when [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] (second buffer) & 0x3 != 0x2, likewise when bit28 is clear in this field (bitmask 0x10000000).
 
The array-count for the first buffer must be <=1, otherwise an error is returned. If the array-count for the first buffer is 0, this will return 0 with the output bool set to 0. The first [[#ApplicationDeliveryInfo]] buffer is validated. An error is thrown when [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] (first buffer) bit1 is clear or bit0 set. An error is thrown when [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] (second buffer) bit1 is clear.
 
When [[#ApplicationDeliveryInfo|RequiredApplicationVersion]] (first or second buffer) is higher than [[#ApplicationDeliveryInfo|ApplicationVersion]] (second buffer), this will return 0 with the output bool set to 0.
 
When [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] (first buffer) bit28 is set (bitmask 0x10000000):
* When [[#ApplicationDeliveryInfo|ApplicationVersion]] (first buffer) >= [[#ApplicationDeliveryInfo|ApplicationVersion]] (second buffer), write 0 to the output bool, otherwise write 1. Then return 0.
Otherwise when the above bit28 is clear:
* When [[#ApplicationDeliveryInfo|ApplicationVersion]] (first buffer) > [[#ApplicationDeliveryInfo|ApplicationVersion]] (second buffer), write 0 to the output bool, otherwise write 1. Then return 0.


==== ListContentMetaKeyToDeliverApplication ====
==== ListContentMetaKeyToDeliverApplication ====
Takes a type-0x6 output buffer containing an array of [[NCM_services#ContentMetaKey|ContentMetaKey]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], a s32, and returns an output s32 total_out.
Takes a type-0x6 output buffer containing an array of [[NCM_services#ContentMetaKey|ContentMetaKey]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], a s32, and returns an output s32 total_out.
This uses the same LocalContentShare check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].


The array-count for ContentMetaKey must be at least 1, and for ApplicationDeliveryInfo it must match 1.
The array-count for ContentMetaKey must be at least 1, and for ApplicationDeliveryInfo it must match 1.


This will only return 1 ContentMetaKey entry. This will not output the entry when the input s32 is larger than 0. This also does other validation, etc.
The [[#ApplicationDeliveryInfo|ApplicationDeliveryInfo]] is validated (ApplicationDeliveryProtocolVersion/HMAC). An error is thrown when [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] bit0 is set.
 
This uses the same ref-count check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
 
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
 
This will only return 1 ContentMetaKey entry. This will not output the entry when the input s32 is larger than 0, or when [[#ApplicationDeliveryInfo|ApplicationDeliveryAttributeTag]] bit1 is clear.


==== NeedsSystemUpdateToDeliverApplication ====
==== NeedsSystemUpdateToDeliverApplication ====
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], and returns an output u8 bool.
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], and returns an output u8 bool.
This uses the same LocalContentShare check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
The [[#SystemDeliveryInfo]] is validated (validation for ApplicationDeliveryProtocolVersion is enabled).


The array-count must match 1.
The array-count must match 1.


After validation etc, this sets the output bool by comparing system-version fields in the [[#SystemDeliveryInfo]]/[[#ApplicationDeliveryInfo]] and with a state field.
The [[#ApplicationDeliveryInfo]] is validated (ApplicationDeliveryProtocolVersion/HMAC).
 
This then runs functionality similar to [[#SelectLatestSystemDeliveryInfo]]:
* [20.0.0+] The following code block now only runs when the SystemDeliveryInfoPlatform from the input [[#SystemDeliveryInfo]] matches the [[System_Settings|sys-setting]].
* Uses the same functionality as [[#SelectLatestSystemDeliveryInfo]] for GetFunctionBlackListSystemVersionToAuthorize, returning the Result on failure.
* The output bool is set to: out_u8!=0 && out_u32 >= [[#SystemDeliveryInfo]] SystemUpdateVersion (only the upper 16bits are used from the SystemUpdateVersion).
 
Otherwise when the output bool is still false, this sets the output bool by comparing system-version fields in the [[#SystemDeliveryInfo]]/[[#ApplicationDeliveryInfo]] and with a state field (state field originates from [[System_Settings|system-setting]] <code>contents_delivery!required_system_version_to_deliver_application</code>).


==== EstimateRequiredSize ====
==== EstimateRequiredSize ====
Line 1,711: Line 1,828:
[[qlaunch]] uses value Any for the StorageId, and value 55556 for the port.
[[qlaunch]] uses value Any for the StorageId, and value 55556 for the port.


An error is thrown if a state ref-count is zero. An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
This uses the same LocalContentShare and ref-count checks as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].


This loops through the input [[NCM_services#ContentMetaKey|ContentMetaKey]] array, throwing an error if the [[NCM_services#ContentMetaType|ContentMetaType]] doesn't match Patch. The input array is copied into state which is used later by the thread for [[NIM_services|nim]] cmd53, max entries is 0x12.
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
 
HasApplicationRecord is called with the input [[NCM_services#ApplicationId|ApplicationId]], an error is returned if the record isn't found.
 
This loops through the input [[NCM_services#ContentMetaKey|ContentMetaKey]] array, throwing an error if the [[NCM_services#ContentMetaType|ContentMetaType]] doesn't match Patch. The input array is copied into state which is used later by the thread for [[NIM_services|nim]] CreateLocalCommunicationReceiveApplicationTask, max entries is 0x12.


This does various setup then creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation. Then the thread does:
This does various setup then creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation. Then the thread does:
Line 1,719: Line 1,840:
* Calls a func which does:
* Calls a func which does:
** Throws an error if a state flag is set.
** Throws an error if a state flag is set.
** Uses [[NIM_services|nim]] cmd53, returning the Result on failure.
** Uses [[NIM_services|nim]] CreateLocalCommunicationReceiveApplicationTask, returning the Result on failure.
** Uses [[NIM_services|nim]] cmd56, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
** Uses [[NIM_services|nim]] RequestLocalCommunicationReceiveApplicationTaskRun, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
*** When the Result from Get is an error, a func is called for filling in the [[#IAsyncResult|IAsyncResult]] ErrorContext with Type4.
** Handles cleanup and returns.
** Handles cleanup and returns.
* On success, this loads various data which is then used for saving a SystemPlayReport when the cached [[System_Settings|system-setting]] "systemreport!enabled" is set.
* On success, this loads various data which is then used for saving a SystemPlayReport when the cached [[System_Settings|system-setting]] "systemreport!enabled" is set.
** The EventId is "receive_app_contents" with ApplicationId <NS ProgramId>.
** The EventId is "receive_app_contents" with ApplicationId <NS ProgramId>.
** This report has the following fields:
*** "ApplicationId"
*** "DestinationVersion"
*** "SourceVersion"
*** "HasApplicationEntity"
*** "HasPatchEntity"
*** "ApplicationStorageId"
*** "PatchStorageId"
*** "Size"
*** "ThroughputKBps"


==== CommitReceiveApplication ====
==== CommitReceiveApplication ====
Takes an input [[NCM_services#ApplicationId|ApplicationId]], no output.
Takes an input [[NCM_services#ApplicationId|ApplicationId]], no output.
This uses the same LocalContentShare and ref-count checks as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.


==== GetReceiveApplicationProgress ====
==== GetReceiveApplicationProgress ====
Takes an input [[NCM_services#ApplicationId|ApplicationId]], returns an output [[#ReceiveApplicationProgress]].
Takes an input [[NCM_services#ApplicationId|ApplicationId]], returns an output [[#ReceiveApplicationProgress]].


An error is thrown if a state ref-count is zero. An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
This uses the same ref-count check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].


Uses [[NIM_services|nim]] cmd67, throwing an error if no task is returned. Then [[NIM_services|nim]] cmd57 is used, returning the error from there on failure. Lastly, this writes the 0x10-bytes from output+8 from the latter cmd to the output [[#ReceiveApplicationProgress]], and returns 0.
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
 
Uses [[NIM_services|nim]] ListApplicationLocalCommunicationReceiveApplicationTask, throwing an error if no task is returned. Then [[NIM_services|nim]] GetLocalCommunicationReceiveApplicationTaskInfo is used, returning the error from there on failure. Lastly, this writes the 0x10-bytes from output+8 from the latter cmd to the output [[#ReceiveApplicationProgress]], and returns 0.


==== RequestSendApplication ====
==== RequestSendApplication ====
Line 1,740: Line 1,878:
[[qlaunch]] uses value 55556 for the port.
[[qlaunch]] uses value 55556 for the port.


An error is thrown if a state ref-count is zero. An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.
This uses the same LocalContentShare and ref-count checks as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
 
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.


The [[NCM_services#ContentMetaType|ContentMetaType]] must match Patch.
This does various setup and loops through the input ContentMetaKey array for initializing the array passed to the nim cmd during the async task. This loop does the following:
* Throws an error if the [[NCM_services#ContentMetaType|ContentMetaType]] in the ContentMetaKey doesn't match Patch.
* Calls a func with the ContentMetaKey and the ApplicationId, throwing an error if the output value is 0.
* Calls a func with the ContentMetaKey for getting the StorageId. This essentially loops through each valid ncm [[NCM_services|IContentMetaDatabase]] using cmd [[NCM_services|Has]] with the input ContentMetaKey, returning the relevant StorageId when found.
* The ContentMetaKey and the StorageId are copied into a tmp struct.
* if (ContentMetaType==Patch && StorageId==GameCard) { <call a func etc> }
* Copies the above tmp struct into the async task state array.


This does various setup and selects a ContentMetaKey to use from the input, then creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation. Then the thread does:
This then creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation. Then the thread does:


* Calls a func which does:
* Calls a func which does:
** Throws an error if a state flag is set.
** Throws an error if a state flag is set.
** Uses [[NIM_services|nim]] cmd60, returning the Result on failure.
** Uses [[NIM_services|nim]] CreateLocalCommunicationSendApplicationTask, returning the Result on failure.
** Uses [[NIM_services|nim]] cmd61, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
** Uses [[NIM_services|nim]] RequestLocalCommunicationSendApplicationTaskRun, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
*** When the Result from Get is an error, a func is called for filling in the [[#IAsyncResult|IAsyncResult]] ErrorContext with Type4.
** Handles cleanup and returns.
** Handles cleanup and returns.
* On success, this loads various data which is then used for saving a SystemPlayReport when the cached [[System_Settings|system-setting]] "systemreport!enabled" is set.
* On success, this loads various data which is then used for saving a SystemPlayReport when the cached [[System_Settings|system-setting]] "systemreport!enabled" is set.
** The EventId is "send_app_contents" with ApplicationId <NS ProgramId>.
** The EventId is "send_app_contents" with ApplicationId <NS ProgramId>.
** This report has the following fields:
*** "ApplicationId"
*** "Version"
*** "ApplicationStorageId"
*** "PatchStorageId"


==== GetSendApplicationProgress ====
==== GetSendApplicationProgress ====
Takes an input [[NCM_services#ApplicationId|ApplicationId]], returns an output [[#SendApplicationProgress]].
Takes an input [[NCM_services#ApplicationId|ApplicationId]], returns an output [[#SendApplicationProgress]].


Same as [[#GetReceiveApplicationProgress]] except this is the Send version, and uses [[NIM_services|nim]] cmd68/cmd63 instead.
Same as [[#GetReceiveApplicationProgress]] except this is the Send version, and uses [[NIM_services|nim]] ListApplicationLocalCommunicationSendApplicationTask/GetLocalCommunicationSendApplicationTaskInfo instead. The data copied to output is also swapped: u64 nim_out+0x8 is copied to out+0x8, and u64 nim_out+0x10 is copied to out+0x0.


==== CompareSystemDeliveryInfo ====
==== CompareSystemDeliveryInfo ====
Line 1,766: Line 1,918:
==== ListNotCommittedContentMeta ====
==== ListNotCommittedContentMeta ====
Takes a type-0x6 output buffer containing an array of [[NCM_services#ContentMetaKey|ContentMetaKey]], a s32, an [[NCM_services#ApplicationId|ApplicationId]], returns an output s32 total_out.
Takes a type-0x6 output buffer containing an array of [[NCM_services#ContentMetaKey|ContentMetaKey]], a s32, an [[NCM_services#ApplicationId|ApplicationId]], returns an output s32 total_out.
This uses the same ref-count check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
An error is thrown if [[NIM_services|nim]] ListApplicationApplyDeltaTask returns a task.


==== RecoverDownloadTask ====
==== RecoverDownloadTask ====
Takes a type-0x5 input buffer containing an array of {unknown} and an input u64, no output.
Takes a type-0x5 input buffer containing an array of {unknown} and an input u64, no output.
This uses the same LocalContentShare and ref-count checks as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].


==== GetApplicationDeliveryInfoHash ====
==== GetApplicationDeliveryInfoHash ====
Takes a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], returns an output 0x20-byte SHA256 hash.
Takes a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], returns an output 0x20-byte SHA256 hash.


This extracts data from the input array for hashing with SHA256, with validation being done when handling each entry.
This uses the same LocalContentShare check as [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]].
 
This extracts data from the input array for hashing with SHA256, with validation being done when handling each entry (ApplicationDeliveryProtocolVersion/HMAC).
 
The 0x14-bytes from [[#ApplicationDeliveryInfo|ApplicationDeliveryInfo]]+0x8 are copied into a 0x18-byte struct entry in an array buffer, with the last 4-bytes being cleared. Then each 0x18-byte struct entry is hashed.
 
==== Cmd2019 ====
Takes a type-0x15 input buffer containing a [[#SystemDeliveryInfo]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], a type-0x5 input buffer containing an array of [[#ApplicationDeliveryInfo]], returns an output u8 bool.
 
This is essentially an extended version of [[#CanDeliverApplication|CanDeliverApplication]], with additional functionality for determining platform compatibility.
 
This calls a func for validating the [[#SystemDeliveryInfo]] from the type-0x15 buffer, returning the Result on failure.
 
Then [[#CanDeliverApplication|CanDeliverApplication]] is called with the output bool and the input arrays, returning the Result on failure.
 
If the output bool is set after calling the above, it then calls a func with the output bool, the second [[#ApplicationDeliveryInfo]] buffer, and the [[#SystemDeliveryInfo]] from the type-0x15 buffer. This func does the following:
* When the SystemDeliveryInfoPlatform from the input [[#SystemDeliveryInfo]] matches the [[System_Settings|sys-setting]], it does the following:
** Uses [[Shared_Database_services|pl:s]] RequestApplicationFunctionAuthorizationByApplicationId with the [[#ApplicationDeliveryInfo]] ApplicationId/ApplicationVersion and ApplicationFunctionAuthorizationId=0x5, handling the Result on failure.
* When the platform fields from the input [[#SystemDeliveryInfo]]/[[#ApplicationDeliveryInfo]] match, write 1 to the output bool and return 0. Otherwise:
** When the [[#SystemDeliveryInfo]] SystemDeliveryInfoPlatform is 0x1 (Ounce): *output = [[#ApplicationDeliveryInfo|ContentMetaPlatform]] == 0 && [[#ApplicationDeliveryInfo|ProperProgramExists]] == 0;
** When the [[#SystemDeliveryInfo]] SystemDeliveryInfoPlatform is 0x0 (NX): write 0 to the output bool and return 0.
** Otherwise, Abort.


==== GetApplicationRightsOnClient ====
==== GetApplicationRightsOnClient ====
Line 1,895: Line 2,074:
No input, returns an output bool.
No input, returns an output bool.


Various Deliver cmds now load the same flag used by this cmd (IsLocalContentShareEnabled), with an error being returned when it's not enabled.
Various Deliver cmds now run essentially the same code as IsLocalContentShareEnabled, with an error being returned when it's not enabled.
 
==== Cmd4026 ====
Takes an input u64, returns an [[#IHostSession|IHostSession]].
 
The input u64 must match a state field.
 
This initializes [[LDN_services|ldn]] etc, and creates a network.
 
==== Cmd4027 ====
Takes an input u64, returns an [[#IClientSession|IClientSession]].
 
The input u64 must match a state field.
 
This initializes [[LDN_services|ldn]] etc.


=== IGameCardStopper ===
=== IGameCardStopper ===
Line 1,951: Line 2,144:
|}
|}


=== IApplicationVersionInterface ===
=== IHostSession ===
This is "nn::ns::detail::IApplicationVersionInterface".
This is "nn::ns::vphym::detail::IHostSession".


This was added with [4.0.0+].
This was added with [20.0.0+].


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 1,960: Line 2,153:
! Cmd || Name
! Cmd || Name
|-
|-
| 0 || GetLaunchRequiredVersion
| 0 ||
|-
| 1 ||
|-
| 2 ||
|}
 
==== Cmd0 ====
No input, returns an output Event handle and an [[#IAsyncValue]].
 
The async task does the following:
* This waits for a client to connect.
* The [[LDN_services|NodeInfo]] UserName is converted into two u64s, which are used to locate a state entry with matching values.
* The client [[LDN_services|NodeInfo]] Ipv4Address is copied into state.
* Then a ptr to the above located state entry is also written into state.
 
==== Cmd1 ====
No input, returns an output Event handle and an [[#IAsyncResult]].
 
The async task uses [[NIM_services|nim]] cmd2018 or cmd2027, depending on a state field. Once finished when a state flag is set, [[LDN_services|ldn]] is finalized and that state flag is cleared.
 
==== Cmd2 ====
No input, returns an output Event handle and an [[#IAsyncResult]].
 
The async task uses [[NIM_sevices|nim]] cmd2024.
 
=== IClientSession ===
This is "nn::ns::vphym::detail::IClientSession".
 
This was added with [20.0.0+].
 
{| class="wikitable" border="1"
|-
! Cmd || Name
|-
| 0 ||
|-
| 1 ||
|-
| 2 ||
|}
 
==== Cmd0 ====
No input, returns an output Event handle and an [[#IAsyncValue]].
 
The async task does the following:
* Uses [[LDN_services|ldn]] Scan.
* After a [[LDN_services|NodeInfo]] is found with a matching UserName, the Ipv4Address for it is copied into state.
* If a timeout didn't occur and a valid NodeInfo was found, it proceeds with connecting to the network.
 
==== Cmd1 ====
No input, returns an output Event handle and an [[#IAsyncResult]].
 
The async task uses [[NIM_services|nim]] cmd2019 or cmd2028, depending on a state field. Once finished when a state flag is set, [[LDN_services|ldn]] is finalized and that state flag is cleared.
 
==== Cmd2 ====
No input, returns an output Event handle and an [[#IAsyncResult]].
 
This is identical to [[#IHostSession|IHostSession]] Cmd2.
 
=== IApplicationVersionInterface ===
This is "nn::ns::detail::IApplicationVersionInterface".
 
This was added with [4.0.0+].
 
{| class="wikitable" border="1"
|-
! Cmd || Name
|-
| 0 || GetLaunchRequiredVersion
|-
|-
| 1 || UpgradeLaunchRequiredVersion
| 1 || UpgradeLaunchRequiredVersion
Line 2,006: Line 2,268:
|-
|-
| 48 || [[#GetFreeSpaceSize]]
| 48 || [[#GetFreeSpaceSize]]
|-
| 58 || [20.1.0+]
|-
| 71 || [20.1.0+]
|-
|-
| 600 || [[#CountApplicationContentMeta]]
| 600 || [[#CountApplicationContentMeta]]
Line 2,043: Line 2,309:
|-
|-
| 92 || [5.0.0+] GetRunningApplicationProgramId
| 92 || [5.0.0+] GetRunningApplicationProgramId
|-
| 100 || [S2]
|-
| 101 || [S2]
|-
|-
| 2524 || [19.0.0+]  
| 2524 || [19.0.0+]  
|}
|}
==== Cmd100 ====
Takes a type-0x16 output buffer containing a 0x300-byte struct, an input u8, an u64. Returns two output u8s.
==== Cmd101 ====
Takes a type-0x16 output buffer containing a 0x300-byte struct, an input u8, an u64. Returns an output u8, an u8 [[Filesystem_services|ContentAttributes]], and a [[NCM_services#ProgramId|ProgramId]].
This is similar to Cmd2524. On [S2] this is used instead of Cmd2524.
==== Cmd2524 ====
Takes a type-0x16 output buffer containing a 0x300-byte struct, an input u8, an u64. Returns an output u8 [[Filesystem_services|ContentAttributes]] and a [[NCM_services#ProgramId|ProgramId]].
The user-process uses the output from this as the input for [[Filesystem_services|OpenFileSystemWithId]] (out-buffer is used as the [[Filesystem_services|FspPath]]).


=== IDownloadTaskInterface ===
=== IDownloadTaskInterface ===
Line 2,116: Line 2,399:
| 2 || [10.0.0+] IsDataCorruptedResult ||
| 2 || [10.0.0+] IsDataCorruptedResult ||
|-
|-
| 3 || [20.0.0+] ||
| 3 || [20.0.0+] [[#ListApplicationRecord|ListApplicationRecord]] ||
|}
|}


Line 2,161: Line 2,444:
|-
|-
| 16 || [20.0.0+] ||
| 16 || [20.0.0+] ||
|-
| 17 || [20.1.0+] ||
|}
|}


Line 2,447: Line 2,732:
| 1202 || [4.0.0+] [[#GetSafeSystemVersion]]
| 1202 || [4.0.0+] [[#GetSafeSystemVersion]]
|-
|-
| 3100 || [18.0.0+]  
| 3100 || [18.0.0+] [[#GetSafeSystemVersionCheckInfo|GetSafeSystemVersionCheckInfo]]
|-
|-
| 3101 || [18.0.0+]  
| 3101 || [18.0.0+] [[#RequestUpdateSafeSystemVersionCheckInfo|RequestUpdateSafeSystemVersionCheckInfo]]
|-
|-
| 3102 || [18.0.0+]  
| 3102 || [18.0.0+] [[#ResetSafeSystemVersionCheckInfo|ResetSafeSystemVersionCheckInfo]]
|}
|}


Line 2,457: Line 2,742:
No input, returns an output u8 bool flag.
No input, returns an output u8 bool flag.


Web-applets use this command to check if the system needs an update.
[S1] Web-applets use this command to check if the system needs an update.


== UpdateSafeSystemVersionForDebug ==
== UpdateSafeSystemVersionForDebug ==
Takes an input [[NCM_services#ApplicationId|ApplicationId]] and an u32 '''version'''.
Takes an input u32 '''version''' and an [[NCM_services#ApplicationId|ApplicationId]].


This command is not available for retail units. On a debug unit, if the [[System_Settings|system setting]] <code>vulnerability!enable_debug</code> is set, this mounts the system savegame [[Flash_Filesystem#System_Savegames|0x8000000000000049]] as "ns_ssversion:/", opens the file "ns_ssversion:/entry" and writes the supplied [[NCM_services#ApplicationId|ApplicationId]] and '''version''' in it.
This command is not available for retail units. On a debug unit, if the [[System_Settings|system setting]] <code>vulnerability!enable_debug</code> is set, this mounts the system savegame [[Flash_Filesystem#System_Savegames|0x8000000000000049]] as "ns_ssversion:/", opens the file "ns_ssversion:/entry" and writes the supplied [[NCM_services#ApplicationId|ApplicationId]] and '''version''' in it.
Line 2,470: Line 2,755:
== GetSafeSystemVersion ==
== GetSafeSystemVersion ==
No input, returns an output [[NCM_services#ContentMetaKey|ContentMetaKey]] with the cached contents of "ns_ssversion:/entry" ([[NCM_services#ApplicationId|ApplicationId]], u32 '''version''' and u32 '''policy''' from <code>vulnerability!needs_update_vulnerability_policy</code>).
No input, returns an output [[NCM_services#ContentMetaKey|ContentMetaKey]] with the cached contents of "ns_ssversion:/entry" ([[NCM_services#ApplicationId|ApplicationId]], u32 '''version''' and u32 '''policy''' from <code>vulnerability!needs_update_vulnerability_policy</code>).
== GetSafeSystemVersionCheckInfo ==
No input, returns 0x10-bytes of output.
[S2] Used by web-applets via ns:vm.
== RequestUpdateSafeSystemVersionCheckInfo ==
No input, returns an output Event handle and an [[#IAsyncResult|IAsyncResult]].
[S2] Used by web-applets via ns:vm.
The async task thread uses [[NIM_services|nim]] RequestCheckSafeSystemVersion, etc.
== ResetSafeSystemVersionCheckInfo ==
No input/output.
This throws an error if [[Settings_services|GetDebugModeFlag]] returns false.


= ns:su =
= ns:su =
Line 2,511: Line 2,813:
|-
|-
| 18 || [4.0.0+] [[#GetSendSystemUpdateProgress]]
| 18 || [4.0.0+] [[#GetSendSystemUpdateProgress]]
|-
| 19 || [S2]
|-
| 20 || [S2]
|}
|}


Line 2,520: Line 2,826:
== OpenSystemUpdateControl ==
== OpenSystemUpdateControl ==
No input, returns an [[#ISystemUpdateControl]].
No input, returns an [[#ISystemUpdateControl]].
Only 1 ISystemUpdateControl can be open at a time.


== NotifyExFatDriverRequired ==
== NotifyExFatDriverRequired ==
Line 2,577: Line 2,885:
[[qlaunch]] uses value 55556 for the port. IP is normally a local-WLAN address, however this can be any address. port/addr are little-endian.
[[qlaunch]] uses value 55556 for the port. IP is normally a local-WLAN address, however this can be any address. port/addr are little-endian.


[[NIM_services|NIM]] will use the input addr/port with [[Sockets_services|bind()]]. During [[Sockets_services|accept()]] handling the addr from there must match the input addr. Hence, addr must be the client addr. [[NIM_services|NIM]] will also eventually verify that the system is not Internet-connected.
See [[NIM_services|nim]] regarding the input addr/port usage, etc.


This validates the [[#SystemDeliveryInfo]] and generates a [[NCM_services#ContentMetaKey|ContentMetaKey]] from that, and creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation. Then the thread does:
[11.0.0+] An error is thrown if LocalContentShare is not [[#IsLocalContentShareEnabled|enabled]].
 
This validates the [[#SystemDeliveryInfo]] and generates a [[NCM_services#ContentMetaKey|ContentMetaKey]] from that, and creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation.
 
The above validation verifies that the HMAC and SystemDeliveryProtocolVersion are valid. The OldSystemUpdateId ([20.0.0+] SystemUpdateId, SystemUpdateIdFlag ignored) must match the Id for the installed SystemUpdate as returned by [[NCM_services|ncm]].
 
Then the thread does:
* Calls a func which does:
* Calls a func which does:
** Uses [[NIM_services|nim]] cmd76, returning the Result on failure.
** Uses [[NIM_services|nim]] CreateLocalCommunicationSendSystemUpdateTask, returning the Result on failure.
** Uses [[NIM_services|nim]] cmd77, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
*** The input firmware_variation is from the [[#SystemDeliveryInfo|FirmwareVariationId]].
** Uses [[NIM_services|nim]] RequestLocalCommunicationSendSystemUpdateTaskRun, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
*** When the Result from Get is an error, a func is called for filling in the [[#IAsyncResult|IAsyncResult]] ErrorContext with Type4.
** Handles cleanup and returns.
** Handles cleanup and returns.
* Unlike [[#RequestReceiveSystemUpdate]], this doesn't save a SystemPlayReport.
* Unlike [[#RequestReceiveSystemUpdate]], this doesn't save a SystemPlayReport.
Line 2,589: Line 2,905:
No input, returns an output [[#SystemUpdateProgress]].
No input, returns an output [[#SystemUpdateProgress]].


Same as [[#GetReceiveProgress]] except this uses nim cmd81 and cmd78.
Same as [[#GetReceiveProgress]] except this uses nim ListLocalCommunicationSendSystemUpdateTask and GetLocalCommunicationSendSystemUpdateTaskInfo. The data copied to output is also swapped: u64 nim_out+0x8 is copied to out+0x8, and u64 nim_out+0x10 is copied to out+0x0.
 
== Cmd19 ==
This is exclusive to S2.
 
No input/output.
 
== Cmd20 ==
This is exclusive to S2.
 
No input, returns an output u8.


== ISystemUpdateControl ==
== ISystemUpdateControl ==
Line 2,644: Line 2,970:
| 22 || [6.0.0+] [[#RequestCheckLatestUpdateIncludesRebootlessUpdate]]
| 22 || [6.0.0+] [[#RequestCheckLatestUpdateIncludesRebootlessUpdate]]
|}
|}
Only 1 ISystemUpdateControl can be open at a time.


All Card cmds except SetupCardUpdate* require [[#SetupCardUpdate]]/[[#SetupCardUpdateViaSystemUpdater]] to be used previously. [[#GetPreparedCardUpdateEulaDataSize]]/[[#GetPreparedCardUpdateEulaData]] checks a different state flag.
All Card cmds except SetupCardUpdate* require [[#SetupCardUpdate]]/[[#SetupCardUpdateViaSystemUpdater]] to be used previously. [[#GetPreparedCardUpdateEulaDataSize]]/[[#GetPreparedCardUpdateEulaData]] checks a different state flag.
Line 2,691: Line 3,015:
*** "DestinationExFatStatus"
*** "DestinationExFatStatus"
*** "Rebootless"
*** "Rebootless"
* Since FIRM will be installed later, the two flags in [[Flash_Filesystem#System_Update_Control]] are set to 1.
* Since BootImagePackage will be installed later, the two flags in [[Flash_Filesystem#System_Update_Control]] are set to 1.
* Uses [[NIM_services|nim]] CommitSystemUpdateTask and [[NIM_services|nim]] DestroySystemUpdateTask.
* Uses [[NIM_services|nim]] CommitSystemUpdateTask and [[NIM_services|nim]] DestroySystemUpdateTask.
* Installs FIRM. After installing each FIRM, the associated flag in [[Flash_Filesystem#System_Update_Control]] is set to 0.
* Installs BootImagePackage. After installing each BootImagePackage, the associated flag in [[Flash_Filesystem#System_Update_Control]] is set to 0.
* On newer system versions when an input flag is set, this uses [[Filesystem_services|NotifySystemDataUpdateEvent]], however this doesn't happen with ApplyDownloadedUpdate since that input flag is 0.
* On newer system versions when an input flag is set, this uses [[Filesystem_services|NotifySystemDataUpdateEvent]], however this doesn't happen with ApplyDownloadedUpdate since that input flag is 0.


Line 2,749: Line 3,073:
No input, returns an output u8 bool.
No input, returns an output u8 bool.


Same as [[#HasDownloaded]] except this uses [[NIM_services|nim]] cmd71 and cmd73.
Same as [[#HasDownloaded]] except this uses [[NIM_services|nim]] ListLocalCommunicationReceiveSystemUpdateTask and GetLocalCommunicationReceiveSystemUpdateTaskInfo.


=== RequestReceiveSystemUpdate ===
=== RequestReceiveSystemUpdate ===
Line 2,756: Line 3,080:
[[qlaunch]] uses the same value for the port as [[#RequestSendSystemUpdate]] (see [[#RequestSendSystemUpdate]] for addr as well).
[[qlaunch]] uses the same value for the port as [[#RequestSendSystemUpdate]] (see [[#RequestSendSystemUpdate]] for addr as well).


[[NIM_services|NIM]] will use the input addr/port with [[Sockets_services|connect()]].
See [[NIM_services|nim]] regarding the input addr/port usage, etc.
 
This uses the same LocalContentShare check as [[#RequestSendSystemUpdate|RequestSendSystemUpdate]].
 
An error is thrown if a state flag is clear.
 
This validates the [[#SystemDeliveryInfo]] (same as [[#RequestSendSystemUpdate|RequestSendSystemUpdate]]) and generates a [[NCM_services#ContentMetaKey|ContentMetaKey]] from that, and creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation.


This validates the [[#SystemDeliveryInfo]] and generates a [[NCM_services#ContentMetaKey|ContentMetaKey]] from that, and creates the [[#IAsyncResult]] + the async thread which handles the [[#IAsyncResult]] operation. Then the thread does:
Then the thread does:


* Calls a func which does:
* Calls a func which does:
** Throws an error if [[NIM_services#ListSystemUpdateTask|ListSystemUpdateTask]] returns any task.
** Throws an error if [[NIM_services#ListSystemUpdateTask|ListSystemUpdateTask]] returns any task.
** Checks whether a sysupdate is actually required using the previously generated [[NCM_services#ContentMetaKey|ContentMetaKey]], throwing an error if not.
** Checks whether a sysupdate is actually required using the previously generated [[NCM_services#ContentMetaKey|ContentMetaKey]] (this func is also passed the below statefield as the last param), throwing an error if not.
** Uses [[NIM_services|nim]] cmd69, returning the Result on failure.
*** [20.0.0+] The above check-sysupdate func was updated (which is also used elsewhere), flag handling during the loop was updated (which uses the last input param).
** Uses [[NIM_services|nim]] cmd72, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
** Uses [[NIM_services|nim]] CreateLocalCommunicationReceiveSystemUpdateTask, returning the Result on failure.
*** The input firmware_variation is from [[System_Settings|system-setting]] <code>ns.systemupdate!firmware_variation</code> or <code>ns.systemupdate!t_firmware_variation</code>, depending on the [[Settings_services|PlatformRegion]] (value 0xFF is used when the output setting-size is invalid).
*** The input '''unk''' is set to: <code>unk = statefield == 0 ? 0x4 : 0xC</code> ([20.0.0+] uses statefield & 1 == 0). [20.0.0+] Additional data is now ORRed with unk afterwards: <code>unk |= ((statefield>>1) & 0x3) << 8;</code> (same statefield as before)
** Uses [[NIM_services|nim]] RequestLocalCommunicationReceiveSystemUpdateTaskRun, returning the Result on failure. Waits for the IAsyncResult operation from this to finish, then uses the Get cmd to get the output Result.
*** When the Result from Get is an error, a func is called for filling in the [[#IAsyncResult|IAsyncResult]] ErrorContext with Type4.
** Handles cleanup and returns.
** Handles cleanup and returns.
* On success, this loads various data which is then used for saving a SystemPlayReport when the cached [[System_Settings|system-setting]] "systemreport!enabled" is set.
* On success, this loads various data which is then used for saving a SystemPlayReport when the cached [[System_Settings|system-setting]] "systemreport!enabled" is set.
Line 2,785: Line 3,119:
No input, returns an output [[#SystemUpdateProgress]].
No input, returns an output [[#SystemUpdateProgress]].


Same as [[#GetDownloadProgress]] except this uses [[NIM_services|nim]] cmd71 and cmd73.
Same as [[#GetDownloadProgress]] except this uses [[NIM_services|nim]] ListLocalCommunicationReceiveSystemUpdateTask and GetLocalCommunicationReceiveSystemUpdateTaskInfo.


=== ApplyReceivedUpdate ===
=== ApplyReceivedUpdate ===
No input/output.
No input/output.
This uses the same LocalContentShare check as [[#RequestSendSystemUpdate|RequestSendSystemUpdate]].


=== GetReceivedEulaDataSize ===
=== GetReceivedEulaDataSize ===
Line 4,410: Line 4,746:
= SystemDeliveryInfo =
= SystemDeliveryInfo =
This is "nn::ns::SystemDeliveryInfo". This is a 0x100-byte struct.
This is "nn::ns::SystemDeliveryInfo". This is a 0x100-byte struct.
Originally the SystemDeliveryInfo validation func verified that OldSystemUpdateId matched the installed SystemUpdate Id. [20.0.0+] The used (Old)SystemUpdateId as selected by SystemUpdateIdFlag must now match one of the Ids in [[System_Settings|system-setting]] <code>contents_delivery!acceptable_system_update_ids_string</code> (replaces the previously mentioned installed-SystemUpdate check).


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 4,425: Line 4,763:
| 0x9 || 0x3 || Reserved.
| 0x9 || 0x3 || Reserved.
|-
|-
| 0xC || 0x4 || SystemUpdateMetaVersion.
| 0xC || 0x4 || SystemUpdateVersion.
|-
| 0x10 || 0x8 || OldSystemUpdateId. [20.0.0+] Always the NX Id: this is loaded from [[System_Settings|system-setting]] <code>contents_delivery!old_system_update_id</code>.
|-
|-
| 0x10 || 0x8 || SystemUpdateMetaId.
| 0x18 || 0x1 || FirmwareVariationId. Used by [[#RequestSendSystemUpdate]]. Loaded from [[System_Settings|system-setting]] <code>ns.systemupdate!firmware_variation</code> or <code>ns.systemupdate!t_firmware_variation</code>, depending on the [[Settings_services|PlatformRegion]].
|-
|-
| 0x18 || 0x1 || FirmwareVariationId. Used by [[#RequestSendSystemUpdate]].
| 0x19 || 0x1 || UpdatableFirmwareGroupId. Unused by [[#RequestSendSystemUpdate]]/[[#RequestReceiveSystemUpdate]], besides HMAC validation. Loaded from [[System_Settings|system-setting]] <code>ns.systemupdate!updatable_firmware_group_id</code> or <code>ns.systemupdate!t_updatable_firmware_group_id</code>, depending on the [[Settings_services|PlatformRegion]].
|-
|-
| 0x19 || 0x1 || UpdatableFirmwareGroupId. Unused by [[#RequestSendSystemUpdate]]/[[#RequestReceiveSystemUpdate]], besides HMAC validation.
| 0x1A || 0x1 || PlatformRegion (0x00 = Unknown/Global, 0x01 = China).
|-
|-
| 0x1A || 0x1 || PlatformRegion (0x00 = Unknown, 0x01 = Global, 0x02 = China).
| 0x1B || 0x1 || [20.0.0+] SystemDeliveryInfoPlatform. Loaded from [[System_Settings|system-setting]] <code>ns.systemupdate!system_delivery_info_platform</code>. Elsewhere this is compared against the sys-setting, etc.
|-
|-
| 0x1B || 0xC5 || Unused by [[#RequestSendSystemUpdate]]/[[#RequestReceiveSystemUpdate]], besides HMAC validation.
| 0x1C || 0x1 || [20.0.0+] SystemUpdateIdFlag. When non-zero, SystemUpdateId is used instead of OldSystemUpdateId. Always set to 0x1 by [[#GetSystemDeliveryInfo]] with [20.0.0+].
|-
| 0x1D || 0x3 || Padding
|-
| 0x20 || 0x8 || [20.0.0+] SystemUpdateId. See above. With [20.0.0+] [[#GetSystemDeliveryInfo]] now writes the Id here instead of OldSystemUpdateId (for the installed SystemUpdate). On S2 this is set to the Ounce Id.
|-
| 0x28 || 0xB8 || Reserved
|-
|-
| 0xE0 || 0x20 || HMAC-SHA256 over the previous 0xE0-bytes.
| 0xE0 || 0x20 || HMAC-SHA256 over the previous 0xE0-bytes.
Line 4,449: Line 4,795:
! Description
! Description
|-
|-
| 0x0 || 0x8 || ?
| 0x0 || 0x4 || ApplicationDeliveryProtocolVersion. Loaded from [[System_Settings|system-setting]] <code>contents_delivery!application_delivery_protocol_version</code>. An error is thrown when [[System_Settings|system-setting]] <code>contents_delivery!application_delivery_protocol_version</code> < version, or when [[System_Settings|system-setting]] <code>contents_delivery!acceptable_application_delivery_protocol_version</code> > version.
|-
| 0x4 || 0x4 || Padding
|-
|-
| 0x8 || 0x8 || ApplicationId.
| 0x8 || 0x8 || ApplicationId.
Line 4,455: Line 4,803:
| 0x10 || 0x4 || ApplicationVersion.
| 0x10 || 0x4 || ApplicationVersion.
|-
|-
| 0x14 || 0x4 || ?
| 0x14 || 0x4 || RequiredApplicationVersion.
|-
|-
| 0x18 || 0x4 || RequiredSystemVersion.
| 0x18 || 0x4 || RequiredSystemVersion.
|-
|-
| 0x1C || 0x4 || ?
| 0x1C || 0x4 || u32 bitmask <code>nn::ns::ApplicationDeliveryAttributeTag</code>. [[#GetApplicationDeliveryInfo|GetApplicationDeliveryInfo]] sets this to the input u32. Bit30 and bit28 are additionally set, depending on [[NCM_services|ContentMetaType]] == Patch, etc.
|-
| 0x20 || 0x1 || [20.0.0+] [[NCM_services|ContentMetaPlatform]]. Loaded from [[NCM_services|ncm]] IContentMetaDatabase GetPlatform.
|-
| 0x21 || 0x1 || [20.0.0+] ProperProgramExists. Set to whether the bit for ProperProgramExists is set from [[NCM_services|ncm]] IContentMetaDatabase GetAttributes.
|-
|-
| 0x20 || 0xC0 || ?
| 0x22 || 0xBE || Reserved
|-
|-
| 0xE0 || 0x20 || HMAC-SHA256 over the previous 0xE0-bytes. Uses a different key than [[#SystemDeliveryInfo]].
| 0xE0 || 0x20 || HMAC-SHA256 over the previous 0xE0-bytes. Uses a different key than [[#SystemDeliveryInfo]].
Retrieved from "https://switchbrew.org/wiki/NS_services"