blob: e2d35d059d58d7cc9ada8430996275429d232f49 [file] [log] [blame]
/*
* Copyright (C) 2020 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.radio@1.6;
import @1.0::CdmaSmsMessage;
import @1.0::Dial;
import @1.0::GsmSmsMessage;
import @1.1::CardPowerState;
import @1.2::DataRequestReason;
import @1.4::EmergencyCallRouting;
import @1.4::EmergencyServiceCategory;
import @1.4::RadioAccessFamily;
import @1.5::IRadio;
import @1.5::AccessNetwork;
import @1.5::DataProfileInfo;
import @1.5::LinkAddress;
/**
* This interface is used by telephony and telecom to talk to cellular radio.
* All the functions have minimum one parameter:
* serial: which corresponds to serial no. of request. Serial numbers must only be memorized for the
* duration of a method call. If clients provide colliding serials (including passing the same
* serial to different methods), multiple responses (one for each method call) must still be served.
* setResponseFunctions must work with @1.6::IRadioResponse and @1.6::IRadioIndication.
*/
interface IRadio extends @1.5::IRadio {
/**
* Toggle radio on and off (for "airplane" mode)
* If the radio is turned off/on the radio modem subsystem
* is expected return to an initialized state. For instance,
* any voice and data calls must be terminated and all associated
* lists emptied.
*
* When setting radio power on to exit from airplane mode to place an emergency call on this
* logical modem, powerOn, forEmergencyCall and preferredForEmergencyCall must be true. In
* this case, this modem is optimized to scan only emergency call bands, until:
* 1) Emergency call is completed; or
* 2) Another setRadioPower_1_5 is issued with forEmergencyCall being false or
* preferredForEmergencyCall being false; or
* 3) Timeout after 30 seconds if dial or emergencyDial is not called.
* Once one of these conditions is reached, the modem should move into normal operation.
*
* @param serial Serial number of request.
* @param powerOn To turn on radio -> on = true, to turn off radio -> on = false.
* @param forEmergencyCall To indication to radio if this request is due to emergency call.
* No effect if powerOn is false.
* @param preferredForEmergencyCall indicate whether the following emergency call will be sent
* on this modem or not. No effect if forEmergencyCall is false, or powerOn is false.
*
* Response callback is IRadioConfigResponse. setRadioPowerResponse_1_6.
* Note this API is the same as the 1.5
*/
oneway setRadioPower_1_6(int32_t serial, bool powerOn, bool forEmergencyCall,
bool preferredForEmergencyCall);
/**
* Returns the data call list. An entry is added when a setupDataCall() is issued and removed
* on a deactivateDataCall(). The list is emptied when setRadioPower() off/on issued or when
* the vendor HAL or modem crashes.
*
* @param serial Serial number of request.
*
* Response function is IRadioResponse.getDataCallListResponse_1_6()
*/
oneway getDataCallList_1_6(int32_t serial);
/**
* Setup a packet data connection. If DataCallResponse.status returns DataCallFailCause:NONE,
* the data connection must be added to data calls and a unsolDataCallListChanged() must be
* sent. The call remains until removed by subsequent unsolDataCallIstChanged(). It may be
* lost due to many factors, including deactivateDataCall() being issued, the radio powered
* off, reception lost or even transient factors like congestion. This data call list is
* returned by getDataCallList() and dataCallListChanged().
*
* The Radio is expected to:
* - Create one data call context.
* - Create and configure a dedicated interface for the context.
* - The interface must be point to point.
* - The interface is configured with one or more addresses and is capable of sending and
* receiving packets. The format is IP address with optional "/" prefix length
* (The format is defined in RFC-4291 section 2.3). For example, "192.0.1.3",
* "192.0.1.11/16", or "2001:db8::1/64". Typically one IPv4 or one IPv6 or one of each. If
* the prefix length is absent, then the addresses are assumed to be point to point with
* IPv4 with prefix length 32 or IPv6 with prefix length 128.
* - Must not modify routing configuration related to this interface; routing management is
* exclusively within the purview of the Android OS.
* - Support simultaneous data call contexts up to DataRegStateResult.maxDataCalls specified
* in the response of getDataRegistrationState.
*
* The differences relative to the 1.5 version of the API are:
* - The addition of new parameters pduSessionId, sliceInfo, trafficDescriptor, and
* matchAllRuleAllowed.
* - If an existing data call should be used for the request, that must be indicated in the
* response by setting SetupDataCallResult::cid to the context id of that call.
*
* @param serial Serial number of request.
* @param accessNetwork The access network to setup the data call. If the data connection cannot
* be established on the specified access network then it should be responded with an error.
* @param dataProfileInfo Data profile info.
* @param roamingAllowed Indicates whether or not data roaming is allowed by the user.
* @param reason The request reason. Must be DataRequestReason:NORMAL or
* DataRequestReason:HANDOVER.
* @param addresses If the reason is DataRequestReason:HANDOVER, this indicates the list of link
* addresses of the existing data connection. This parameter must be ignored unless reason
* is DataRequestReason:HANDOVER.
* @param dnses If the reason is DataRequestReason:HANDOVER, this indicates the list of DNS
* addresses of the existing data connection. The format is defined in RFC-4291 section 2.2.
* For example, "192.0.1.3" or "2001:db8::1". This parameter must be ignored unless reason
* is DataRequestReason:HANDOVER.
* @param pduSessionId The pdu session id to be used for this data call. A value of 0 means
* no pdu session id was attached to this call.
* Reference: 3GPP TS 24.007 section 11.2.3.1b
* @param sliceInfo SliceInfo to be used for the data connection when a handover occurs from
* EPDG to 5G. It is valid only when accessNetwork is AccessNetwork:NGRAN. If the slice
* passed from EPDG is rejected, then the data failure cause must be
* DataCallFailCause:SLICE_REJECTED.
* @param trafficDescriptor TrafficDescriptor for which data connection needs to be
* established. It is used for URSP traffic matching as described in TS 24.526
* Section 4.2.2. It includes an optional DNN which, if present, must be used for traffic
* matching -- it does not specify the end point to be used for the data call. The end
* point is specified by DataProfileInfo.apn; DataProfileInfo.apn must be used as the end
* point if one is not specified through URSP rules.
* @param matchAllRuleAllowed bool to indicate if using default match-all URSP rule for this
* request is allowed. If false, this request must not use the match-all URSP rule and if
* a non-match-all rule is not found (or if URSP rules are not available) it should return
* failure with cause DataCallFailCause:MATCH_ALL_RULE_NOT_ALLOWED. This is needed as some
* requests need to have a hard failure if the intention cannot be met, for example, a
* zero-rating slice.
*
* Response function is IRadioResponse.setupDataCallResponse_1_6()
*
*/
oneway setupDataCall_1_6(int32_t serial, AccessNetwork accessNetwork,
DataProfileInfo dataProfileInfo, bool roamingAllowed,
DataRequestReason reason, vec<LinkAddress> addresses, vec<string> dnses,
int32_t pduSessionId, OptionalSliceInfo sliceInfo,
OptionalTrafficDescriptor trafficDescriptor, bool matchAllRuleAllowed);
/**
* Send an SMS message
*
* @param serial Serial number of request.
* @param message GsmSmsMessage as defined in types.hal
*
* Response function is IRadioResponse.sendSmsResponse_1_6()
*
* Note this API is the same as the 1.0
*
* Based on the return error, caller decides to resend if sending sms
* fails. RadioError:SMS_SEND_FAIL_RETRY means retry (i.e. error cause is 332)
* and RadioError:GENERIC_FAILURE means no retry (i.e. error cause is 500)
*/
oneway sendSms_1_6(int32_t serial, GsmSmsMessage message);
/**
* Send an SMS message. Identical to sendSms_1_6,
* except that more messages are expected to be sent soon. If possible,
* keep SMS relay protocol link open (eg TS 27.005 AT+CMMS command)
*
* @param serial Serial number of request.
* @param message GsmSmsMessage as defined in types.hal
*
* Response function is IRadioResponse.sendSmsExpectMoreResponse_1_6()
*
* Note this API is the same as the 1.0
*
* Based on the return error, caller decides to resend if sending sms
* fails. RadioError:SMS_SEND_FAIL_RETRY means retry (i.e. error cause is 332)
* and RadioError:GENERIC_FAILURE means no retry (i.e. error cause is 500)
*/
oneway sendSmsExpectMore_1_6(int32_t serial, GsmSmsMessage message);
/**
* Send a CDMA SMS message
*
* @param serial Serial number of request.
* @param sms Cdma Sms to be sent described by CdmaSmsMessage in types.hal
*
* Response callback is IRadioResponse.sendCdmaSmsResponse_1_6()
*
* Note this API is the same as the 1.0
*
*/
oneway sendCdmaSms_1_6(int32_t serial, CdmaSmsMessage sms);
/**
* Send an SMS message. Identical to sendCdmaSms_1_6,
* except that more messages are expected to be sent soon.
*
* @param serial Serial number of request.
* @param sms Cdma Sms to be sent described by CdmaSmsMessage in types.hal
*
* Response callback is IRadioResponse.sendCdmaSMSExpectMoreResponse_1_6()
*
* Note this API is the same as the 1.5
*
*/
oneway sendCdmaSmsExpectMore_1_6(int32_t serial, CdmaSmsMessage sms);
/**
* Set SIM card power state.
* Request is used to power off or power on the card. It should not generate
* a CardState.CARDSTATE_ABSENT indication, since the SIM is still physically
* inserted.
*
* @param serial Serial number of request
* @param powerUp POWER_DOWN if powering down the SIM card,
* POWER_UP if powering up the SIM card,
* POWER_UP_PASS_THROUGH if powering up the SIM card in
* pass through mode.
*
* When SIM card is in POWER_UP_PASS_THROUGH, the modem does not send
* any command to it (for example SELECT of MF, or TERMINAL
* CAPABILITY), and the SIM card is controlled completely by Telephony
* sending APDUs directly. The SIM card state must be
* RIL_CARDSTATE_PRESENT and the number of card apps will be 0.
* No new error code is generated. Emergency calls are supported in
* the same way as if the SIM card is absent.
* Pass-through mode is valid only for the specific card session where
* it is activated, and normal behavior occurs at the next SIM
* initialization, unless POWER_UP_PASS_THROUGH is requested again.
*
* The device is required to power down the SIM card before it can
* switch the mode between POWER_UP and POWER_UP_PASS_THROUGH.
* At device power up, the SIM interface is powered up automatically.
* Each subsequent request to this method is processed only after the
* completion of the previous one.
*
* When the SIM is in POWER_DOWN, the modem should send an empty vector of
* AppStatus in CardStatus.applications. If a SIM in the POWER_DOWN state
* is removed and a new SIM is inserted, the new SIM should be in POWER_UP
* mode by default. If the device is turned off or restarted while the SIM
* is in POWER_DOWN, then the SIM should turn on normally in POWER_UP mode
* when the device turns back on.
*
* Response callback is IRadioResponse.setSimCardPowerResponse_1_6().
* Note that this differs from setSimCardPower_1_1 in that the response
* callback should only be sent once the device has finished executing
* the request (the SIM has finished powering on or off).
*/
oneway setSimCardPower_1_6(int32_t serial, CardPowerState powerUp);
/**
* Enable or disable E-UTRA-NR dual connectivity. If disabled then UE will not connect
* to secondary carrier.
*
* @param serial Serial number of request.
* @param nrDualConnectivityState expected NR dual connectivity state.
* 1. Enable NR dual connectivity {NrDualConnectivityState:ENABLE}
* 2. Disable NR dual connectivity {NrDualConnectivityState:DISABLE}
* 3. Disable NR dual connectivity and force secondary cell to be released
* {NrDualConnectivityState:DISABLE_IMMEDIATE}
*
* Response callback is IRadioResponse.setNRDualConnectivityStateResponse()
*/
oneway setNrDualConnectivityState(int32_t serial,
NrDualConnectivityState nrDualConnectivityState);
/**
* Is E-UTRA-NR Dual Connectivity enabled
*
* @param serial Serial number of request.
* Response callback is IRadioResponse.isNRDualConnectivityEnabledResponse()
*/
oneway isNrDualConnectivityEnabled(int32_t serial);
/**
* Reserves an unallocated pdu session id from the pool of ids.
*
* The allocated id is returned in the response.
*
* When the id is no longer needed, call releasePduSessionId to
* return it to the pool.
*
* Reference: 3GPP TS 24.007 section 11.2.3.1b
*
* @param serial Serial number of request.
*
* Response function is IRadioResponse.allocatePduSessionIdResponse()
*/
oneway allocatePduSessionId(int32_t serial);
/**
* Releases a pdu session id that was previously allocated using
* allocatePduSessionId.
*
* Reference: 3GPP TS 24.007 section 11.2.3.1b
* @param serial Serial number of request.
* @param id Pdu session id to release.
*
* Response function is IRadioResponse.releasePduSessionIdResponse()
*/
oneway releasePduSessionId(int32_t serial, int32_t id);
/**
* Indicates that a handover to the IWLAN transport has begun.
*
* Any resources being transferred to the IWlan transport cannot be released while a
* handover is underway. For example, if a pdu session id needs to be
* transferred to IWlan, then, the modem should not release the id while
* the handover is in progress.
*
* If a handover was unsuccessful, then the framework calls IRadio::cancelHandover.
* The modem retains ownership over any of the resources being transferred to IWlan.
*
* If a handover was successful, the framework calls IRadio::deactivateDataCall with reason
* HANDOVER. The IWlan transport now owns the transferred resources and is responsible for
* releasing them.
*
* @param serial Serial number of request.
* @param id callId The identifier of the data call which is provided in SetupDataCallResult
*
* Response function is IRadioResponse.startHandoverResponse()
*/
oneway startHandover(int32_t serial, int32_t callId);
/**
* Indicates that a handover was cancelled after a call to IRadio::startHandover.
*
* Since the handover was unsuccessful, the modem retains ownership over any of the resources
* being transferred and is still responsible for releasing them.
*
* @param serial Serial number of request.
* @param id callId The identifier of the data call which is provided in SetupDataCallResult
*
* Response function is IRadioResponse.cancelHandoverResponse()
*/
oneway cancelHandover(int32_t serial, int32_t callId);
/**
* Requests to set the network type for searching and registering.
*
* Instruct the radio to *only* accept the types of network provided.
* setPreferredNetworkType, setPreferredNetworkTypesBitmap will not be called anymore
* except for IRadio v1.5 or older devices.
*
* In case of an emergency call, the modem is authorized to bypass this
* restriction.
*
* @param serial Serial number of request.
* @param networkTypeBitmap a 32-bit bearer bitmap of RadioAccessFamily
*
* Response callback is IRadioResponse.setAllowedNetworkTypesBitmapResponse()
*/
oneway setAllowedNetworkTypesBitmap(
uint32_t serial, bitfield<RadioAccessFamily> networkTypeBitmap);
/**
* Requests bitmap representing the currently allowed network types.
*
* getPreferredNetworkType, getPreferredNetworkTypesBitmap will not be called anymore
* except for IRadio v1.5 or older devices.
*
* @param serial Serial number of request.
*
* Response callback is IRadioResponse.getAllowedNetworkTypesBitmapResponse()
*/
oneway getAllowedNetworkTypesBitmap(int32_t serial);
/**
* Control data throttling at modem.
* - DataThrottlingAction:NO_DATA_THROTTLING should clear any existing
* data throttling within the requested completion window.
* - DataThrottlingAction:THROTTLE_SECONDARY_CARRIER: Remove any existing
* throttling on anchor carrier and achieve maximum data throttling on
* secondary carrier within the requested completion window.
* - DataThrottlingAction:THROTTLE_ANCHOR_CARRIER: disable secondary
* carrier and achieve maximum data throttling on anchor carrier by
* requested completion window.
* - DataThrottlingAction:HOLD: Immediately hold on to current level of
* throttling.
*
* @param serial Serial number of request.
* @param dataThrottlingAction DataThrottlingAction as defined in types.hal
* @param completionDurationMillis window, in milliseconds, in which the
* requested throttling action has to be achieved. This must be 0 when
* dataThrottlingAction is DataThrottlingAction:HOLD.
*
* Response function is IRadioResponse.setDataThrottlingResponse()
*/
oneway setDataThrottling(int32_t serial,
DataThrottlingAction dataThrottlingAction,
int64_t completionDurationMillis);
/**
* Initiate emergency voice call, with zero or more emergency service category(s), zero or
* more emergency Uniform Resource Names (URN), and routing information for handling the call.
* Android uses this request to make its emergency call instead of using @1.0::IRadio.dial
* if the 'address' in the 'dialInfo' field is identified as an emergency number by Android.
*
* In multi-sim scenario, if the emergency number is from a specific subscription, this radio
* request can still be sent out on the other subscription as long as routing is set to
* @1.4::EmergencyNumberRouting#EMERGENCY. This radio request will not be sent on an inactive
* (PIN/PUK locked) subscription unless both subscriptions are PIN/PUK locked. In this case,
* the request will be sent on the primary subscription.
*
* Some countries or carriers require some emergency numbers that must be handled with normal
* call routing if possible or emergency routing. 1) if the 'routing' field is specified as
* @1.4::EmergencyNumberRouting#NORMAL, the implementation must try the full radio service to
* use normal call routing to handle the call; if service cannot support normal routing, the
* implementation must use emergency routing to handle the call. 2) if 'routing' is specified
* as @1.4::EmergencyNumberRouting#EMERGENCY, the implementation must use emergency routing to
* handle the call. 3) if 'routing' is specified as @1.4::EmergencyNumberRouting#UNKNOWN,
* Android does not know how to handle the call.
*
* If the dialed emergency number does not have a specified emergency service category, the
* 'categories' field is set to @1.4::EmergencyServiceCategory#UNSPECIFIED; if the dialed
* emergency number does not have specified emergency Uniform Resource Names, the 'urns' field
* is set to an empty list. If the underlying technology used to request emergency services
* does not support the emergency service category or emergency uniform resource names, the
* field 'categories' or 'urns' may be ignored.
*
* In the scenarios that the 'address' in the 'dialInfo' field has other functions besides the
* emergency number function, if the 'hasKnownUserIntentEmergency' field is true, the user's
* intent for this dial request is emergency call, and the modem must treat this as an actual
* emergency dial; if the 'hasKnownUserIntentEmergency' field is false, Android does not know
* user's intent for this call.
*
* If 'isTesting' is true, this request is for testing purpose, and must not be sent to a real
* emergency service; otherwise it's for a real emergency call request.
*
* Reference: 3gpp 22.101, Section 10 - Emergency Calls;
* 3gpp 23.167, Section 6 - Functional description;
* 3gpp 24.503, Section 5.1.6.8.1 - General;
* RFC 5031
*
* @param serial Serial number of request.
* @param dialInfo the same @1.0::Dial information used by @1.0::IRadio.dial.
* @param categories bitfield<@1.4::EmergencyServiceCategory> the Emergency Service Category(s)
* of the call.
* @param urns the emergency Uniform Resource Names (URN)
* @param routing @1.4::EmergencyCallRouting the emergency call routing information.
* @param hasKnownUserIntentEmergency Flag indicating if user's intent for the emergency call
* is known.
* @param isTesting Flag indicating if this request is for testing purpose.
*
* Response function is IRadioResponse.emergencyDialResponse()
*/
oneway emergencyDial_1_6(int32_t serial, Dial dialInfo,
bitfield<EmergencyServiceCategory> categories, vec<string> urns,
EmergencyCallRouting routing, bool hasKnownUserIntentEmergency, bool isTesting);
/**
* Get which bands the modem's background scan is acting on.
*
* @param serial Serial number of request.
*
* Response callback is IRadioResponse.getSystemSelectionChannelsResponse()
*/
oneway getSystemSelectionChannels(int32_t serial);
/**
* Request all of the current cell information known to the radio. The radio
* must return list of all current cells, including the neighboring cells. If for a particular
* cell information isn't known then the appropriate unknown value will be returned.
* This does not cause or change the rate of unsolicited cellInfoList().
*
* This is identical to getCellInfoList in V1.0, but it requests updated version of CellInfo.
*
* @param serial Serial number of request.
*
* Response callback is IRadioResponse.getCellInfoListResponse()
*/
oneway getCellInfoList_1_6(int32_t serial);
/**
* Request current voice registration state.
*
* @param serial Serial number of request.
*
* Response function is IRadioResponse.getVoiceRegistrationStateResponse_1_6()
*/
oneway getVoiceRegistrationState_1_6(int32_t serial);
/**
* Requests current signal strength and associated information. Must succeed if radio is on.
*
* @param serial Serial number of request.
*
* Response function is IRadioResponse.getSignalStrengthResponse_1_6()
*/
oneway getSignalStrength_1_6(int32_t serial);
/**
* Request current data registration state.
*
* @param serial Serial number of request.
*
* Response function is IRadioResponse.getDataRegistrationStateResponse_1_6()
*/
oneway getDataRegistrationState_1_6(int32_t serial);
/**
* Requests current call list
*
* @param serial Serial number of request.
*
* Response function is IRadioResponse.getCurrentCallsResponse_1_6()
*/
oneway getCurrentCalls_1_6(int32_t serial);
/**
* Request to get the current slicing configuration including URSP rules and
* NSSAIs (configured, allowed and rejected).
* URSP stands for UE route selection policy and is defined in 3GPP TS 24.526
* Section 4.2.
* An NSSAI is a collection of network slices. Each network slice is identified by
* an S-NSSAI and is represented by the struct SliceInfo. NSSAI and S-NSSAI
* are defined in 3GPP TS 24.501.
*
* Response function is IRadioResponse.getSlicingConfigResponse()
*/
oneway getSlicingConfig(int32_t serial);
/**
* Provide Carrier specific information to the modem that must be used to
* encrypt the IMSI and IMPI. Sent by the framework during boot, carrier
* switch and everytime the framework receives a new certificate.
*
* @param serial Serial number of request.
* @param imsiEncryptionInfo ImsiEncryptionInfo as defined in types.hal.
*
* Response callback is
* IRadioResponse.setCarrierInfoForImsiEncryptionResponse()
*
* Note this API is the same as the 1.1 version except using the 1.6 ImsiEncryptionInfo
* as the input param.
*/
oneway setCarrierInfoForImsiEncryption_1_6(int32_t serial, @1.6::ImsiEncryptionInfo imsiEncryptionInfo);
/**
* Get the local and global phonebook records from the SIM card.
* This should be called again after a simPhonebookChanged notification is received.
*
* The phonebook records are received via IRadioIndication.simPhonebookRecordsReceived()
*
* @param serial Serial number of request.
*
* Response callback is IRadioResponse.getSimPhonebookRecordsResponse()
*/
oneway getSimPhonebookRecords(int32_t serial);
/**
* Get the phone book capacity
*
* @param serial Serial number of request.
*
* Response function is defined from IRadioResponse.getSimPhonebookCapacityResponse()
*/
oneway getSimPhonebookCapacity(int32_t serial);
/**
* Insert, delete or update a phonebook record on the SIM card.
* If the index of recordInfo is 0, the phonebook record will be added to global or
* local phonebook, and global phonebook has higher priority than local phonebook.
*
* If the fields in the recordInfo are all empty except for the index, the phonebook
* record specified by the index will be deleted.
*
* The indication simPhonebookChanged will be called after every successful call of
* updateSimPhonebookRecords.
*
* @param serial Serial number of request.
* @param recordInfo Details of the record to insert, delete or update.
*
* Response callback is IRadioResponse.updateSimPhonebookRecordsResponse()
*/
oneway updateSimPhonebookRecords(int32_t serial, PhonebookRecordInfo recordInfo);
};