এআইডিএল-এ টীকা

AIDL এমন টীকা সমর্থন করে যা AIDL কম্পাইলারকে টীকাযুক্ত উপাদান সম্পর্কে অতিরিক্ত তথ্য দেয়, যা জেনারেট করা স্টাব কোডকেও প্রভাবিত করে।

সিনট্যাক্সটি জাভার মতোই:

@AnnotationName(argument1=value, argument2=value) AidlEntity

এখানে, AnnotationName হল টীকার নাম, এবং AidlEntity হল একটি AIDL সত্তা যেমন interface Foo , void method() , অথবা int arg । এটি অনুসরণকারী সত্তার সাথে একটি টীকা সংযুক্ত করা হয়।

কিছু টীকাতে প্রথম বন্ধনীর ভেতরে আর্গুমেন্ট সেট করা থাকতে পারে, যেমন উপরে দেখানো হয়েছে। যে টীকাগুলিতে কোন আর্গুমেন্ট নেই তাদের প্রথম বন্ধনীর প্রয়োজন হয় না। উদাহরণস্বরূপ:

@AnnotationName AidlEntity

এই টীকাগুলি জাভা টীকাগুলির মতো নয়, যদিও এগুলি দেখতে খুব একই রকম। ব্যবহারকারীরা কাস্টম AIDL টীকাগুলি সংজ্ঞায়িত করতে পারে না; টীকাগুলি সমস্ত পূর্বনির্ধারিত। কিছু টীকা শুধুমাত্র একটি নির্দিষ্ট ব্যাকএন্ডকে প্রভাবিত করে এবং অন্যান্য ব্যাকএন্ডে অ-অপারেশন থাকে। তাদের বিভিন্ন সীমাবদ্ধতা রয়েছে যেখানে সেগুলি সংযুক্ত করা যেতে পারে।

এখানে পূর্বনির্ধারিত AIDL টীকাগুলির তালিকা রয়েছে:

বাতিলযোগ্য

nullable ঘোষণা করে যে টীকাযুক্ত সত্তার মান প্রদান করা যাবে না।

এই টীকাটি শুধুমাত্র মেথড রিটার্ন টাইপ, মেথড প্যারামিটার এবং পার্সেলযোগ্য ফিল্ডের সাথে সংযুক্ত করা যেতে পারে।

interface IFoo {
    // method return types
    @nullable Data method();

    // method parameters
    void method2(in @nullable Data d);
}

parcelable Data {
    // parcelable fields
    @nullable Data d;
}

আদিম প্রকারের সাথে টীকা সংযুক্ত করা যাবে না। নিম্নলিখিতটি একটি ত্রুটি।

void method(in @nullable int a); // int is a primitive type

এই অ্যানোটেশনটি জাভা ব্যাকএন্ডের জন্য no-option। কারণ, জাভাতে, সমস্ত অ-প্রাথমিক প্রকার রেফারেন্স দ্বারা পাস করা হয়, যা null হতে পারে।

CPP ব্যাকএন্ডে, @nullable T ম্যাপ করে Android 11 বা তার নিচের ভার্সনে std::unique_ptr<T> এবং Android 12 বা তার উপরের ভার্সনে std::optional<T> ।

NDK ব্যাকএন্ডে, @nullable T সর্বদা std::optional<T> তে ম্যাপ করে।

রাস্ট ব্যাকএন্ডে, @nullable T সর্বদা Option<T> তে ম্যাপ করে।

তালিকার মতো টাইপ L যেমন T[] অথবা List<T> জন্য, @nullable L std::optional<std::vector<std::optional<T>>> (অথবা Android 11 বা তার নিচের ভার্সনের CPP ব্যাকএন্ডের ক্ষেত্রে std::unique_ptr<std::vector<std::unique_ptr<T>>> ) ম্যাপ করে।

এই ম্যাপিংয়ের একটি ব্যতিক্রম আছে। যখন T হল IBinder অথবা AIDL ইন্টারফেস, তখন Rust ছাড়া সকল ব্যাকএন্ডের জন্য @nullable নো-অপ। অন্য কথায়, @nullable IBinder এবং IBinder উভয়ই android::sp<IBinder> তে সমানভাবে ম্যাপ করে, যা ইতিমধ্যেই nullable কারণ এটি একটি শক্তিশালী পয়েন্টার (CPP এখনও nullability প্রয়োগ করে, কিন্তু টাইপটি এখনও android::sp<IBinder> )। Rust-এ, এই প্রকারগুলি শুধুমাত্র @nullable দিয়ে টীকা করা হলেই nullable হয়। টীকা করা হলে Option<T> তে ম্যাপ করা হয়।

অ্যান্ড্রয়েড ১৩ থেকে শুরু করে, @nullable(heap=true) ব্যবহার করে পার্সেলযোগ্য ফিল্ডগুলিকে পুনরাবৃত্ত প্রকারের মডেল তৈরি করা যেতে পারে। @nullable(heap=true) পদ্ধতির প্যারামিটার বা রিটার্ন প্রকারের সাথে ব্যবহার করা যাবে না। এটি দিয়ে টীকা করা হলে, ক্ষেত্রটি CPP/NDK ব্যাকএন্ডে একটি হিপ-বরাদ্দকৃত রেফারেন্স std::unique_ptr<T> -এ ম্যাপ করা হয়। @nullable(heap=true) জাভা ব্যাকএন্ডে নো-অপ।

utf8InCpp সম্পর্কে

utf8InCpp ঘোষণা করে যে CPP ব্যাকএন্ডের জন্য একটি String UTF8 ফর্ম্যাটে উপস্থাপন করা হয়েছে। এর নাম অনুসারে, অ্যানোটেশনটি অন্যান্য ব্যাকএন্ডের জন্য একটি নো-অপ। বিশেষ করে, String সর্বদা জাভা ব্যাকএন্ডে UTF16 এবং NDK ব্যাকএন্ডে UTF8 থাকে।

এই অ্যানোটেশনটি String টাইপ ব্যবহার করা যেতে পারে এমন যেকোনো জায়গায় সংযুক্ত করা যেতে পারে, যার মধ্যে রিটার্ন মান, প্যারামিটার, ধ্রুবক ঘোষণা এবং পার্সেলযোগ্য ক্ষেত্র অন্তর্ভুক্ত।

CPP ব্যাকএন্ডের জন্য, AIDL-এর @utf8InCpp String std::string এ ম্যাপ করে, যেখানে String অ্যানোটেশন ছাড়াই android::String16 এ ম্যাপ করে যেখানে UTF16 ব্যবহার করা হয়।

মনে রাখবেন যে utf8InCpp অ্যানোটেশনের অস্তিত্ব তারের উপর স্ট্রিং ট্রান্সমিট করার পদ্ধতি পরিবর্তন করে না। স্ট্রিংগুলি সর্বদা তারের উপর UTF16 হিসাবে ট্রান্সমিট করা হয়। একটি utf8InCpp অ্যানোটেটেড স্ট্রিং ট্রান্সমিট করার আগে UTF16 এ রূপান্তরিত হয়। যখন একটি স্ট্রিং গ্রহণ করা হয়, তখন এটি UTF16 থেকে UTF8 এ রূপান্তরিত হয় যদি এটি utf8InCpp হিসাবে অ্যানোটেটেড হয়।

ভিন্টফস্টেবিলিটি

VintfStability ঘোষণা করে যে একটি ব্যবহারকারী-সংজ্ঞায়িত প্রকার (ইন্টারফেস, পার্সেলেবল এবং এনাম) সিস্টেম এবং বিক্রেতা ডোমেন জুড়ে ব্যবহার করা যেতে পারে। সিস্টেম-বিক্রেতা আন্তঃকার্যকারিতা সম্পর্কে আরও জানতে HAL-এর জন্য AIDL দেখুন।

অ্যানোটেশনটি টাইপের স্বাক্ষর পরিবর্তন করে না, কিন্তু যখন এটি সেট করা হয়, তখন টাইপের উদাহরণটি স্থিতিশীল হিসাবে চিহ্নিত করা হয় যাতে এটি বিক্রেতা এবং সিস্টেম প্রক্রিয়া জুড়ে ভ্রমণ করতে পারে।

এখানে দেখানো হিসাবে, অ্যানোটেশনটি শুধুমাত্র ব্যবহারকারী-সংজ্ঞায়িত ধরণের ঘোষণার সাথে সংযুক্ত করা যেতে পারে:

@VintfStability
interface IFoo {
    ....
}

@VintfStability
parcelable Data {
    ....
}

@VintfStability
enum Type {
    ....
}

যখন কোন টাইপ VintfStability দিয়ে টীকা করা হয়, তখন টাইপটিতে উল্লেখিত অন্য যেকোনো টাইপকেও একইভাবে টীকা করা উচিত। নিম্নলিখিত উদাহরণে, Data এবং IBar উভয়কেই VintfStability দিয়ে টীকা করা উচিত।

@VintfStability
interface IFoo {
    void doSomething(in IBar b); // references IBar
    void doAnother(in Data d); // references Data
}

@VintfStability // required
interface IBar {...}

@VintfStability // required
parcelable Data {...}

এছাড়াও, VintfStability দিয়ে টীকাযুক্ত প্রকার নির্ধারণকারী AIDL ফাইলগুলি শুধুমাত্র aidl_interface Soong মডিউল প্রকার ব্যবহার করে তৈরি করা যেতে পারে, যেখানে stability বৈশিষ্ট্য "vintf" তে সেট করা থাকে।

aidl_interface {
    name: "my_interface",
    srcs: [...],
    stability: "vintf",
}

অসমর্থিত অ্যাপ ব্যবহার

UnsupportedAppUsage অ্যানোটেশনটি নির্দেশ করে যে টীকাযুক্ত AIDL টাইপটি নন-SDK ইন্টারফেসের অংশ যা লিগ্যাসি অ্যাপগুলির জন্য অ্যাক্সেসযোগ্য। লুকানো API গুলি সম্পর্কে আরও তথ্যের জন্য নন-SDK ইন্টারফেসের উপর বিধিনিষেধ দেখুন।

UnsupportedAppUsage অ্যানোটেশনটি জেনারেট করা কোডের আচরণকে প্রভাবিত করে না। অ্যানোটেশনটি শুধুমাত্র একই নামের জাভা অ্যানোটেশন দিয়ে জেনারেট করা জাভা ক্লাসটি অ্যানোট করে।

// in AIDL
@UnsupportedAppUsage
interface IFoo {...}

// in Java
@android.compat.annotation.UnsupportedAppUsage
public interface IFoo {...}

এটি জাভা ব্যাকএন্ডের বাইরের ব্যবহারকারীদের জন্য একটি নো-অপশন।

ব্যাকিং

Backing টীকাটি একটি AIDL enum ধরণের স্টোরেজ ধরণ নির্দিষ্ট করে।

@Backing(type="int")
enum Color { RED, BLUE, }

CPP ব্যাকএন্ডে, এটি int32_t টাইপের একটি C++ enum ক্লাস নির্গত করে।

enum class Color : int32_t {
    RED = 0,
    BLUE = 1,
}

যদি টীকাটি বাদ দেওয়া হয়, তাহলে type byte বলে ধরে নেওয়া হয়, যা CPP ব্যাকএন্ডের জন্য int8_t এ ম্যাপ করে।

type আর্গুমেন্ট শুধুমাত্র নিম্নলিখিত ইন্টিগ্রাল টাইপগুলিতে সেট করা যেতে পারে:

• byte (৮-বিট প্রশস্ত)
• int (৩২-বিট প্রশস্ত)
• long (৬৪-বিট প্রশস্ত)

NdkOnlyStableপার্সেলেবল

NdkOnlyStableParcelable একটি parceable ঘোষণা (সংজ্ঞা নয়) স্থিতিশীল হিসাবে চিহ্নিত করে যাতে এটি অন্যান্য স্থিতিশীল AIDL প্রকার থেকে উল্লেখ করা যায়। এটি JavaOnlyStableParcelable এর মতো, কিন্তু NdkOnlyStableParcelable একটি parceable ঘোষণাকে জাভার পরিবর্তে NDK ব্যাকএন্ডের জন্য স্থিতিশীল হিসাবে চিহ্নিত করে।

এই পার্সেবল ব্যবহার করতে:

• আপনাকে ndk_header উল্লেখ করতে হবে।
• আপনার অবশ্যই একটি NDK লাইব্রেরি থাকতে হবে যেখানে parcelable উল্লেখ থাকবে এবং লাইব্রেরিটি লাইব্রেরিতে কম্পাইল করা থাকতে হবে। উদাহরণস্বরূপ, cc_* মডিউলের কোর বিল্ড সিস্টেমে, static_libs অথবা shared_libs ব্যবহার করুন। aidl_interface এর জন্য, Android.bp এ additional_shared_libraries অধীনে লাইব্রেরিটি যোগ করুন।

জাভাঅনলিস্টেবলপার্সেলেবল

JavaOnlyStableParcelable একটি পার্সেলযোগ্য ঘোষণা (সংজ্ঞা নয়) স্থিতিশীল হিসাবে চিহ্নিত করে যাতে এটি অন্যান্য স্থিতিশীল AIDL প্রকার থেকে উল্লেখ করা যায়।

স্থিতিশীল AIDL-এর জন্য ব্যবহারকারী-সংজ্ঞায়িত সকল প্রকার স্থিতিশীল থাকা আবশ্যক। পার্সেবলের জন্য, স্থিতিশীল হওয়ার জন্য AIDL সোর্স ফাইলে এর ক্ষেত্রগুলি স্পষ্টভাবে বর্ণনা করা প্রয়োজন।

parcelable Data { // Data is a structured parcelable.
    int x;
    int y;
}

parcelable AnotherData { // AnotherData is also a structured parcelable
    Data d; // OK, because Data is a structured parcelable
}

যদি পার্সেলেবলটি অসংগঠিত (অথবা কেবল ঘোষিত) হয়, তাহলে এটি উল্লেখ করা যাবে না।

parcelable Data; // Data is NOT a structured parcelable

parcelable AnotherData {
    Data d; // Error
}

যখন আপনি যে পার্সেলেবলটি উল্লেখ করছেন তা ইতিমধ্যেই Android SDK-এর অংশ হিসেবে নিরাপদে উপলব্ধ থাকে, তখন JavaOnlyStableParcelable আপনাকে চেকটি ওভাররাইড করতে দেয়।

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

জাভাডেরিভ

JavaDerive স্বয়ংক্রিয়ভাবে জাভা ব্যাকএন্ডে পার্সেলযোগ্য ধরণের জন্য পদ্ধতি তৈরি করে।

@JavaDerive(equals = true, toString = true)
parcelable Data {
  int number;
  String str;
}

কী তৈরি করতে হবে তা নিয়ন্ত্রণ করার জন্য অ্যানোটেশনের অতিরিক্ত প্যারামিটার প্রয়োজন। সমর্থিত প্যারামিটারগুলি হল:

• equals=true equals এবং hashCode পদ্ধতি তৈরি করে।
• toString=true toString মেথড তৈরি করে যা টাইপ এবং ফিল্ডের নাম প্রিন্ট করে। উদাহরণস্বরূপ: Data{number: 42, str: foo}

জাভাডিফল্ট

Android 13-এ যোগ করা JavaDefault , ডিফল্ট বাস্তবায়ন সংস্করণ সমর্থন তৈরি করা হয়েছে কিনা তা নিয়ন্ত্রণ করে ( setDefaultImpl এর জন্য)। স্থান বাঁচানোর জন্য এই সমর্থনটি আর ডিফল্টভাবে তৈরি করা হয় না।

জাভাপাসথ্রু

JavaPassthrough জেনারেটেড জাভা API-কে একটি ইচ্ছামত জাভা অ্যানোটেশন দিয়ে টীকাবদ্ধ করতে দেয়।

AIDL-এ নিম্নলিখিত টীকাগুলি

@JavaPassthrough(annotation="@android.annotation.Alice")
@JavaPassthrough(annotation="@com.android.Alice(arg=com.android.Alice.Value.A)")

হত্তয়া

@android.annotation.Alice
@com.android.Alice(arg=com.android.Alice.Value.A)

তৈরি জাভা কোডে।

annotation প্যারামিটারের মান সরাসরি নির্গত হয়। AIDL কম্পাইলার প্যারামিটারের মান খতিয়ে দেখে না। যদি কোনও জাভা-স্তরের সিনট্যাক্স ত্রুটি থাকে, তবে তা AIDL কম্পাইলার দ্বারা নয় বরং জাভা কম্পাইলার দ্বারা ধরা পড়বে।

এই টীকাটি যেকোনো AIDL সত্তার সাথে সংযুক্ত করা যেতে পারে। এই টীকাটি জাভা ব্যাকএন্ডের বাইরের ব্যবহারকারীদের জন্য একটি নো-অপ।

রাস্টডাইরভ

RustDerive স্বয়ংক্রিয়ভাবে জেনারেটেড রাস্ট ধরণের জন্য বৈশিষ্ট্য প্রয়োগ করে।

কী তৈরি করতে হবে তা নিয়ন্ত্রণ করার জন্য অ্যানোটেশনের অতিরিক্ত প্যারামিটার প্রয়োজন। সমর্থিত প্যারামিটারগুলি হল:

• Copy=true
• Clone=true
• Ord=true
• PartialOrd=true
• Eq=true
• PartialEq=true
• Hash=true

এই বৈশিষ্ট্যগুলির ব্যাখ্যার জন্য, https://doc.rust-lang.org দেখুন।

স্থির আকার

FixedSize একটি স্ট্রাকচার্ড পার্সেলেবলকে স্থির আকার হিসেবে চিহ্নিত করে। একবার চিহ্নিত হয়ে গেলে, পার্সেলেবলে নতুন ক্ষেত্র যোগ করার অনুমতি থাকবে না। পার্সেলেবলের সমস্ত ক্ষেত্র অবশ্যই স্থির আকারের ধরণের হতে হবে, যার মধ্যে রয়েছে আদিম প্রকার, এনাম, স্থির-আকারের অ্যারে এবং FixedSize দিয়ে চিহ্নিত অন্যান্য পার্সেলেবল।

বর্ণনাকারী

Descriptor জোরপূর্বক একটি ইন্টারফেসের ইন্টারফেস বর্ণনাকারী নির্দিষ্ট করে।

package android.foo;

@Descriptor(value="android.bar.IWorld")
interface IHello {...}

এই ইন্টারফেসের বর্ণনাকারী হল android.bar.IWorld । যদি Descriptor অ্যানোটেশনটি অনুপস্থিত থাকে, তাহলে বর্ণনাকারী হবে android.foo.IHello ।

এটি ইতিমধ্যে প্রকাশিত ইন্টারফেসের নাম পরিবর্তনের জন্য কার্যকর। পুনঃনামকরণের আগে পুনঃনামকরণ করা ইন্টারফেসের বর্ণনাকারীকে ইন্টারফেসের বর্ণনাকারীর মতো করে তৈরি করলে দুটি ইন্টারফেস একে অপরের সাথে কথা বলতে পারবে।

মন্তব্যে @লুকান

AIDL কম্পাইলার মন্তব্যে @hide সনাক্ত করে এবং মেটালাভার জন্য জাভা আউটপুটে এটি প্রেরণ করে। এই মন্তব্যটি নিশ্চিত করে যে অ্যান্ড্রয়েড বিল্ড সিস্টেম জানে যে AIDL API গুলি SDK API নয়।

মন্তব্যে @অপ্রচলিত

AIDL কম্পাইলার মন্তব্যে @deprecated একটি ট্যাগ হিসেবে স্বীকৃতি দেয় যা AIDL সত্তাকে সনাক্ত করে যা আর ব্যবহার করা উচিত নয়।

interface IFoo {
  /** @deprecated use bar() instead */
  void foo();
  void bar();
}

প্রতিটি ব্যাকএন্ড অবচয়প্রাপ্ত সত্তাগুলিকে একটি ব্যাকএন্ড-নির্দিষ্ট অ্যানোটেশন বা অ্যাট্রিবিউট দিয়ে চিহ্নিত করে যাতে ক্লায়েন্ট কোডটি অবচয়প্রাপ্ত সত্তাগুলিকে উল্লেখ করলে সতর্ক করা হয়। উদাহরণস্বরূপ, @Deprecated অ্যানোটেশন এবং @deprecated ট্যাগ জাভা জেনারেটেড কোডের সাথে সংযুক্ত থাকে।