בתוך חבילות OTA

המערכת יוצרת את הקובץ הבינארי של המעדכן מ-bootable/recovery/updater ומשתמשת בו בחבילת OTA.

החבילה עצמה היא קובץ ZIP (ota_update.zip, incremental_ota_update.zip) שמכיל את הקובץ הבינארי להפעלה META-INF/com/google/android/update-binary .

המעדכן מכיל מספר פונקציות מובנות ותרגום של כתיבת סקריפט שניתן להרחבה (edify) שתומכת בפקודות למשימות אופייניות שקשורות לעדכון. מראה המעדכן בקובץ ה-ZIP של החבילה, בשביל סקריפט שבקובץ META-INF/com/google/android/updater-script

הערה: השימוש בסקריפט edify ו/או בפונקציות המובנות אינו נפוץ פעילות, אבל היא יכולה להיות שימושית אם צריך לנפות באגים בקובץ העדכון.

עדכון התחביר

סקריפט עדכון הוא ביטוי יחיד שבו כל הערכים הם מחרוזות. מחרוזות ריקות הן false בהקשר בוליאני וכל שאר המחרוזות הן true. ב-Edify יש תמיכה את האופרטורים הבאים (עם המשמעויות הרגילות):

(expr )
 expr + expr  # string concatenation, not integer addition
 expr == expr
 expr != expr
 expr && expr
 expr || expr
 ! expr
 if expr then expr endif
 if expr then expr else expr endif
 function_name(expr, expr,...)
 expr; expr

כל מחרוזת של התווים a-z, A-Z, 0-9, _, :, /, . זו לא מילה שמורה, נחשב לליטרל של מחרוזת. (מילים שמורות הן אם אחר ואז endif.) מחרוזת (String) מילוליים עשויים להופיע גם במירכאות כפולות; כך יוצרים ערכים עם רווחים לבנים תווים אחרים שלא נכללים בקבוצה שלמעלה. \n, \t, \", ו-\\ משמשים כסימן בריחה (escape) במירכאות מחרוזות, כמו גם \x##.

&& וגם || האופרטורים יוצרים מקוצרים; הצד הימני לא מוערך התוצאה הלוגית נקבעת על ידי הצד השמאלי. הערכים הבאים מקבילים:

e1 && e2
if e1 then e2 endif

; האופרטור הוא נקודה ברצף. זה אומר להעריך קודם את הצד השמאלי, ואז את מימין. הערך שלו הוא הערך של הביטוי בצד ימין. יכול להופיע גם תו נקודה-פסיק אחרי ביטוי, כך שהאפקט מדמה הצהרות בסגנון C:

prepare();
do_other_thing("argument");
finish_up();

פונקציות מובנות

רוב פונקציונליות העדכון כלולה בפונקציות שזמינות להפעלה על ידי סקריפטים. (במילים מחמירות אלה הן פקודות מאקרו ולא פונקציות בחוש ה-Lisp, כי הם לא צריכים להעריך את כל הארגומנטים). אם לא צוין אחרת, הפונקציות מחזירות true עבור הצלחה ו-false עבור שגיאה. אם רוצים ששגיאות יבטלו את הביצוע של צריך להשתמש בפונקציות abort() או assert(). הקבוצה של אפשר להרחיב גם את הפונקציות שזמינות במעדכן, פונקציונליות ספציפית למכשיר.

abort([msg])

המערכת מבטלת את ההפעלה של הסקריפט באופן מיידי, באמצעות הוספת msg (לא חובה). אם למשתמש יש מופעלת בתצוגת הטקסט, msg תופיע ביומן השחזור ובמסך.

assert(expr[, expr, ...])

הפונקציה בוחנת כל Expr בנפרד. אם זה לא נכון, המערכת מבטלת מיד את הביצוע באמצעות הפונקציה ההודעה "assert failed" וטקסט המקור של הביטוי שנכשל.

apply_patch(src_file, tgt_file, tgt_sha1, tgt_size, patch1_sha1, patch1_blob, [...])

מחיל תיקון בינארי על src_file כדי ליצור את tgt_file. אם היעד הרצוי זהה למקור, מעבירים את "-" של tgt_file . tgt_sha1 וגם tgt_size הוא הגיבוב SHA1 הסופי הצפוי והגודל של קובץ היעד. השאר הארגומנטים חייבים להגיע בזוגות: גיבוב SHA1 (מחרוזת הקסדצימלית באורך 40 תווים) ו-blob. ה-blob הוא התיקון שצריך להחיל כשהתוכן הנוכחי של קובץ המקור כולל את ה-SHA1 הנתון.

התיקון מתבצע בצורה בטוחה שמבטיחה שקובץ היעד כולל את הגיבוב והגודל הרצויים של SHA1, או שלא בוצעו בהם שינויים - הוא לא יישאר בלתי ניתן לשחזור במצב ביניים. אם התהליך נקטע במהלך התיקון, יכול להיות שקובץ היעד במצב ביניים; קיים עותק במחיצת המטמון, לכן צריך להפעיל מחדש את העדכון יכול לעדכן בהצלחה את הקובץ.

יש תמיכה בתחביר מיוחד לטיפול בתוכן של מכשיר טכנולוגיית זיכרון (MTD) מחיצות כקבצים, כדי לאפשר תיקון של מחיצות גולמיות כמו אתחול. לקרוא MTD עליכם לדעת כמה נתונים תרצו לקרוא, מכיוון שאין למחיצה רעיון של סוף קובץ. אפשר להשתמש במחרוזת "MTD:partition:size_1:sha1_1:size_2: sha1_2" בתור filename כדי לקרוא את המחיצה הנתונה. עליך לציין ערך אחד לפחות צמד (size, sha-1); אפשר לציין יותר מאפשרות אחת אם יש כמה האפשרויות למה שאתם מצפים לקרוא.

apply_patch_check(filename, sha1[, sha1, ...])

פונקציה זו מחזירה את הערך true אם התוכן של filename או העותק הזמני במחיצת המטמון (אם קיים) סיכום ביקורת (checksum) SHA1 שווה לאחד מערכי sha1 הנתונים. ערכי sha1 מצוינים כ-40 ספרות הקסדצימליות. הפונקציה הזו שונה sha1_check(read_file(filename), sha1 [, ...]) כי הוא יודע לבדוק את עותק המחיצה של המטמון, כדי ש-apply_patch_check() יצליח גם אם הקובץ נפגם על ידי apply_patch() update שהופסק.

apply_patch_space(bytes)

פונקציה זו מחזירה את הערך true אם יש לפחות בייטים של שטח גירוד נתונים בינארי תיקונים.

concat(expr[, expr, ...])

הפונקציה בוחנת כל ביטוי ומשרשרת אותם. האופרטור + הוא תחביר תחבירי עבור זה במקרה המיוחד של שני ארגומנטים (אבל צורת הפונקציה יכולה לכלול כל מספר ). הביטויים חייבים להיות מחרוזות; הוא לא יכול לשרשר blobs.

file_getprop(filename, key)

קורא את שם הקובץ הנתון, מפרש אותו כקובץ מאפיינים (למשל /system/build.prop), ומחזיר את הערך של המפתח הנתון , או אם לא קיים מפתח, מחרוזת ריקה.

format(fs_type, partition_type, location, fs_size, mount_point)

מעצב מחדש מחיצה נתונה. סוגי מחיצות נתמכים:

• fs_type="yaffs2" ו-partition_type="MTD". המיקום חייב להיות השם של ה-MTD מחיצה; מערכת קבצים ריקה מסוג yaffs2 נבנתה שם. הארגומנטים הנותרים הם לא בשימוש.
• fs_type="ext4" ו-partition_type="EMMC". המיקום חייב להיות הקובץ של המכשיר מחיצה. מערכת הקבצים ext4 ריקה. אם fs_size שווה אפס, הערך של הפרמטר מערכת הקבצים תופסת את כל המחיצה. אם fs_size הוא מספר חיובי, הפונקציה מערכת הקבצים מקבלת את fs_size הבייטים הראשונים של המחיצה. אם fs_size הוא מספר שלילי, מערכת הקבצים מקבלת את כל הבייטים מלבד |fs_size| הבייטים האחרונים מחיצה.
• fs_type="f2fs" ו-partition_type="EMMC". המיקום חייב להיות הקובץ של המכשיר מחיצה. fs_size חייב להיות מספר לא שלילי. אם fs_size שווה אפס, הערך של הפרמטר מערכת הקבצים תופסת את כל המחיצה. אם fs_size הוא מספר חיובי, הפונקציה מערכת הקבצים מקבלת את fs_size הבייטים הראשונים של המחיצה.
• הפרמטר load_point צריך להיות נקודת הטעינה העתידית של מערכת הקבצים.

getprop(key)

מחזירה את הערך של המפתח של מאפיין המערכת (או של המחרוזת הריקה, אם הוא לא מוגדר). הערכים של מאפייני המערכת שמוגדרים על ידי מחיצת השחזור לא בהכרח זהים ל- של המערכת הראשית. הפונקציה הזו מחזירה את הערך ב-recovery.

greater_than_int(a, b)

הפונקציה מחזירה true אם ורק אם (iff) a (בפירוש מספר שלם) גדול מ- b (מבוטא כמספר שלם).

ifelse(cond, e1[, e2])

הפונקציה בוחנת את cond, ואם הערך הוא True, מחזירה את הערך e1 ומחזירה אותו. אחרת, הוא יבצע הערכה ויחזיר את הערך e2 (אם קיים). האפשרות "אם ... אחר כך ... ואז ... endif" הוא פשוט סוכר תחבירי לפונקציה הזו.

is_mounted(mount_point)

מחזיר True אם יש מערכת קבצים שטעונה ב-MAX_point.

is_substring(needle, haystack)

מחזירה את הערך iff needle הוא מחרוזת משנה של haystack.

less_than_int(a, b)

הפונקציה מחזירה true iff a (בפירוש כמספר שלם) קטן מ-b (במשמעות של: מספר שלם).

mount(fs_type, partition_type, name, mount_point)

טוענת מערכת קבצים של fs_type ב-MAX_point. partition_type חייב להיות אחת מהאפשרויות:

• MTD. Name הוא השם של מחיצת MTD (למשל: מערכת, נתוני משתמש; ראו /proc/mtd במכשיר כדי להציג רשימה מלאה).
• EMMC.

כברירת מחדל, השחזור לא טוען מערכות קבצים כלשהן (מלבד כרטיס SD, אם המשתמש התקנה ידנית של חבילה מכרטיס ה-SD); הסקריפט צריך לטעון שהוא צריך לשנות.

package_extract_dir(package_dir, dest_dir)

מחלץ את כל הקבצים מהחבילה שמתחת ל-package_dir וכותב אותם ב לעץ התואם שמתחת ל-dest_dir. כל הקבצים הקיימים יוחלפו.

package_extract_file(package_file[, dest_file])

משלים package_file יחיד מחבילת העדכון וכותב אותו אל dest_file ומחליף קבצים קיימים במקרה הצורך. בלי הארגומנט dest_file, מחזיר את התוכן של קובץ החבילה כ-blob בינארי.

read_file(filename)

קוראת את filename ומחזירה את התוכן שלו כ-blob בינארי.

run_program(path[, arg, ...])

מפעיל את הקובץ הבינארי ב-path ומעביר args. הפונקציה מחזירה את סטטוס הסיום של התוכנית.

set_progress(frac)

מגדיר את המיקום של מד ההתקדמות בתוך המקטע שהוגדר לפי העדכני ביותר שיחת show_progress(). הפרמטר frac חייב להיות בטווח [0.0, 1.0]. ההתקדמות אף פעם לא זז אחורה, המערכת תתעלם מניסיונות לעשות זאת.

sha1_check(blob[, sha1])

הארגומנט blob הוא blob מהסוג שהוחזר על ידי read_file() או צורת ארגומנט אחד של package_extract_file() . ללא ארגומנטים מסוג sha1, הפונקציה הזו מחזירה את הגיבוב SHA1 של ה-blob (כמחרוזת הקסדצימלית בת 40 ספרות). עם אחד או יותר sha1, הפונקציה הזו מחזירה את הגיבוב SHA1 אם הוא שווה לאחד ארגומנטים, או את המחרוזת הריקה אם הוא לא שווה לאף אחד מהם.

show_progress(frac, secs)

העברה של מד ההתקדמות בחלק הבא של האורך שלו secs שניות (חייב להיות מספר שלם). שניות עשויות להיות 0. במקרה כזה, המונה לא מתקדמת אוטומטית, אלא באמצעות שימוש בפונקציה set_progress() שהוגדרה למעלה.

sleep(secs)

שינה למשך שניות שניות (חייב להיות מספר שלם).

stdout(expr[, expr, ...])

מעריכה כל ביטוי ומעתיקה את הערך שלו ל-stdout. שימושי לניפוי באגים.

tune2fs(device[, arg, …])

התאמת ארגומנטים של פרמטרים שניתנים לכוונון במכשיר.

ui_print([text, ...])

הפונקציה משרשרת את כל ארגומנטים מסוג text ומדפיסה את התוצאה לממשק המשתמש (כאשר היא תהיה גלויות אם המשתמש הפעיל את תצוגת הטקסט).

unmount(mount_point)

מנתקים את מערכת הקבצים שטעונה ב-MAX_point.

wipe_block_device(block_dev, len)

מתבצעת מחיקה של len הבייטים של מכשיר החסימה הנתון block_dev.

wipe_cache()

גורם למחיקה של מחיצת המטמון בסיום התקנה מוצלחת.

write_raw_image(filename_or_blob, partition)

כותבת את התמונה ב-filename_or_blob למחיצה של MTD. filename_or_blob יכול להיות מחרוזת שנותנת שם לקובץ מקומי או ארגומנט בעל ערך blob שמכיל את הנתונים לכתיבה. כדי להעתיק קובץ מחבילת OTA למחיצה, משתמשים בישויות הבאות: write_raw_image(package_extract_file("zip_filename"), "partition_name");

הערה: לפני Android 4.1, התקבלו רק שמות קבצים, כדי שניתן יהיה להשיג את הנתונים האלה צריך קודם לפרוס לקובץ מקומי זמני.