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

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

সিনট্যাক্স জাভা এর অনুরূপ:

@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

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

CPP ব্যাকএন্ডে, @nullable T ম্যাপ এন্ড্রয়েড 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>>> (বা std::unique_ptr<std::vector<std::unique_ptr<T>>> Android 11 বা তার নিচের জন্য CPP ব্যাকএন্ডের ক্ষেত্রে)।

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

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

utf8InCpp

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

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

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

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

VintfStability

VintfStability ঘোষণা করে যে একটি ব্যবহারকারী-সংজ্ঞায়িত প্রকার (ইন্টারফেস, পার্সেলেবল, এবং enum) সিস্টেম এবং বিক্রেতা ডোমেন জুড়ে ব্যবহার করা যেতে পারে। সিস্টেম-ভেন্ডার ইন্টারঅপারেবিলিটি সম্পর্কে আরও জানতে 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 (8-বিট প্রশস্ত)
• int (32-বিট প্রশস্ত)
• long (64-বিট প্রশস্ত)

NdkOnlyStableParcelable

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

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

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

JavaOnlyStableParcelable

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
}

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

@JavaOnlyStableParcelable
parcelable Data;

parcelable AnotherData {
    Data d; // OK
}

JavaDerive

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

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

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

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

জাভা ডিফল্ট

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

জাভাপাসথ্রু

JavaPassthrough জেনারেট করা Java 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 সত্তার সাথে সংযুক্ত করা যেতে পারে। এই টীকাটি অ-জাভা ব্যাকএন্ডের জন্য একটি নো-অপ।

ফিক্সড সাইজ

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

এটি বিভিন্ন বিটনেস জুড়ে কোনো গ্যারান্টি প্রদান করে না এবং মিশ্র-বিটনেস যোগাযোগের জন্য নির্ভর করা উচিত নয়।

বর্ণনাকারী

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

package android.foo;

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

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

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

@ কমেন্টে লুকান

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

মন্তব্যে @অবঞ্চিত

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

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

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